You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fineract.apache.org by ar...@apache.org on 2022/05/12 08:08:08 UTC
[fineract] branch develop updated: FINERACT-1471: AsciiDoc extension for read/write/batch separation
This is an automated email from the ASF dual-hosted git repository.
arnold pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/develop by this push:
new a89fe5393 FINERACT-1471: AsciiDoc extension for read/write/batch separation
a89fe5393 is described below
commit a89fe539372ecbe50f6e8359938de1402082e339
Author: taskain7 <ta...@gmail.com>
AuthorDate: Fri May 6 13:38:34 2022 +0200
FINERACT-1471: AsciiDoc extension for read/write/batch separation
---
.../src/docs/en/chapters/deployment/index.adoc | 2 +
.../docs/en/chapters/deployment/instance-type.adoc | 177 +++++++++++++++++++++
2 files changed, 179 insertions(+)
diff --git a/fineract-doc/src/docs/en/chapters/deployment/index.adoc b/fineract-doc/src/docs/en/chapters/deployment/index.adoc
index c622891ad..e1b8f9fe6 100644
--- a/fineract-doc/src/docs/en/chapters/deployment/index.adoc
+++ b/fineract-doc/src/docs/en/chapters/deployment/index.adoc
@@ -8,6 +8,8 @@ include::local.adoc[leveloffset=+1]
include::appserver.adoc[leveloffset=+1]
+include::instance-type.adoc[leveloffset=+1]
+
include::kubernetes.adoc[leveloffset=+1]
include::aws.adoc[leveloffset=+1]
diff --git a/fineract-doc/src/docs/en/chapters/deployment/instance-type.adoc b/fineract-doc/src/docs/en/chapters/deployment/instance-type.adoc
new file mode 100644
index 000000000..78fad6515
--- /dev/null
+++ b/fineract-doc/src/docs/en/chapters/deployment/instance-type.adoc
@@ -0,0 +1,177 @@
+= Fineract Instance types
+
+In cases where Fineract has to deal with high load, it can cause a performance problem for a single Fineract instance.
+To overcome this problem, Fineract instances can be started in different instance types for better scalability and performance in a multi-instance environment:
+
+.Fineract instance types
+* Read instance
+* Write instance
+* Batch instance
+
+Each instance type comes with different restrictions. The specifics can be found in the table below.
+
+.Instance types
+|===
+^| ^| Read instance ^| Write instance ^| Batch instance
+
+| Using only read-only DB connection | Yes | No | No
+| Batch jobs are automatically scheduled or startable via API | No | No | Yes
+| Can receive events (business events, hook template events) | No | Yes | No
+| Can send events (business events, hook template events) | No | Yes | Yes
+| Read APIs supported | Yes | Yes | No
+| Write APIs supported | No | Yes | No
+| Batch job APIs supported | No | No | Yes
+| Liquibase migration initiated upon startup | No | Yes |No
+|===
+
+== Configuring instance types in single instance setup
+
+If Fineract is running as a single instance, then all of the 3 instance types should be enabled. In this case, there is no need to worry about the configuration, because this is the default behavior.
+
+[ditaa, target="single-instance-diagram"]
+----
+ +---------+
+ | |
+ | Read |
+ | Write |
+ | Batch |
+ | |
+ +----+----+
+ |
+ v
+ +----------------+
+ |{s} |
+ | Fineract DB |
+ | |
+ +----------------+
+----
+
+== Configuring instance types in multi-instance setup
+
+A common solution to dealing with the high load is to deploy 1 write and 1 batch instances and deploy multiple read instances with read replicas of the Fineract database.
+In this case, the write instance and the database will be freed from part of the load, because read request will use the separated read instance and its read replica database.
+
+[ditaa, target="multiple-read-instances-diagram"]
+----
+ +---------+ +---------+ +---------+ +---------+
+ | | | | | | | |
+ | | | | | | | |
+ | Write | | Batch | | Read | [...] | Read |
+ | | | | | | | |
+ | | | | | | | |
+ +----+----+ +----+----+ +----+----+ +----+----+
+ | | | |
+ +-------+--------+ | |
+ | | |
+ v v v
+ +----------------+ +-------------+ +-------------+
+ |{s} | |{s} | |{s} |
+ | Fineract DB +-=----->+ Read |[...]| Read |
+ | | | Replica | | Replica |
+ +----------------+ +-------------+ +-------------+
+ | ^
+ | |
+ +-----=-------------------------------------+
+----
+
+Also a common scenario when Close of Business jobs are running and Fineract has to deal with a high amount of processes.
+(In a future release) Fineract (will be) is able to run this CoB jobs in batches.
+In multi-instances environment these CoB jobs can run on multiple batch instances and they don't have any impact on the performance of the read and write processes.
+The best practice is to deploy 1 master batch instance and multiple worker batch instances.
+
+[ditaa, target="multiple-batch-instances-diagram"]
+----
+ +---------+ +---------+ +---------+ +---------+ +---------+
+ | | | | | | | | | |
+ | | | | | | | | | |
+ | Read | | Write | | Batch | | Batch | [...] | Batch |
+ | | | | | Manager | | Worker | | Worker |
+ | | | | | | | | | |
+ +----+----+ +----+----+ +----+----+ +----+----+ +----+----+
+ | | | | |
+ +----------------+---------------+-----------------+-------------------+
+ |
+ v
+ +----------------+
+ |{s} |
+ | Fineract DB |
+ | |
+ +----------------+
+----
+These soultions can be mixed with each other, based on the load of the Fineract deployment.
+
+== Configuring instance type via environment variables
+
+The Fineract instance type is configurable via environment variables for the following 3 values:
+
+.Environment variables
+|===
+^| Instance type ^| Environment variable
+
+| Read instance | FINERACT_READ_MODE_ENABLED
+| Write instance | FINERACT_WRITE_MODE_ENABLED
+| Batch instance | FINERACT_BATCH_MODE_ENABLED
+|===
+
+The environment variable values are booleans (true/false). The Fineract instance can be configured in any combination of these instance types, although if all 3 configurations are false, startup will fail. The default value for all 3 values is true.
+
+The configured Fineract instance types are easily accessible via a single Spring bean, named `FineractProperties.FineractModeProperties` that has 4 methods: `isReadMode()`, `isWriteMode()`, `isBatchMode()`, `isReadOnlyMode()`
+
+== Liquibase Database Migration
+
+Liquibase data migration is allowed only for write instances
+
+== APIs
+
+=== Read APIs are allowed only for read and write instances
+
+A Fineract instance is ONLY able to serve read API calls when it’s configured as a read or write instance. In batch instance mode, it won’t serve read API calls.
+If it’s a read or write instance, the read APIs will be served.
+If it’s a batch instance, the read APIs won't be served and a proper HTTP status code will be returned.
+The distinction whether something is a read API can be decided based on the HTTP request method. If it’s a GET, we can assume it’s a read call.
+
+=== Write APIs are allowed only for write instances
+
+A Fineract instance is ONLY able to serve write API calls when it’s configured as a write instance. In read or batch instance mode, it won't serve write API calls.
+If the write APIs won't be served and a proper HTTP status code will be returned.
+If it’s a write instance, the write APIs will be served except the ones related to batch jobs.
+The distinction whether something is a write API can be decided based on the HTTP request method. If it’s non-GET, we can assume it’s a write call. Also, the write APIs related to batch jobs (starting/stopping jobs) will not be served either.
+
+=== Batch job APIs are allowed only for batch instances
+
+A Fineract instance is ONLY able to serve batch API calls when it’s configured as a batch instance. In read or write instance mode, it won’t serve batch API calls.
+If the batch APIs won't be served and and a proper HTTP status code will be returned.
+If it’s a batch instance, the batch APIs will be served.
+
+== Batch jobs
+
+=== Batch job scheduling is allowed only for batch instances
+
+Batch jobs are scheduled only if the Fineract instance running as a batch instance
+
+
+== Read-only instance type restrictions
+
+If the read mode is enabled, but the write mode and batch mode are disabled, Fineract instance runs in read-only mode.
+
+=== Events are disabled for read-only instances
+
+When a Fineract instance is running in read-only mode, all event receiving/sending will be disabled.
+
+=== Read-only tenant connection support
+
+With read separation, there’s a possibility to use read-only database connections for read-only instances.
+If the instance is read-only , the DataSource connection used for the tenant will be read-only.
+If the instance is read-only and the configuration for the read-only datasource is not set, the application startup will fail.
+
+== Batch-only instance type restrictions
+
+If the batch mode is enabled, but the read mode and write mode are disabled, Fineract instance runs in batch-only mode.
+
+=== Receiving events is disabled for batch-only instances
+
+When a Fineract instance is running as batch, event receiving will be disabled while sending events will be still possible since the batch jobs are potentially generating business events.
+
+
+
+