Microservice Starter (msvc)

Description

Starts user/project microservices (external processes). The composition of domain microservices is determined by the `mservices` domain center entity class. Processes are started in the same Docker container where the platform itself runs. A separate folder is created for each microservice in the node working directory, the archive contents are unpacked there, and it becomes the working directory.

According to the `mservice` entity settings, starts the service in active-passive or active-active mode, on all sites or on specific ones.

The process is started with the folder into which the archive was unpacked as its working directory. This path is "/var/lib/era/_workdir/<NODE>/mservices/<DOMAIN>/<ENTITY_NAME>". Simultaneously, a file `/var/lib/era/_workdir/<NODE>/mservices/<DOMAIN>/<ENTITY_NAME>.pid` is created containing the active OS process PID.
If the process crashes, it is immediately restarted by the port management genserver, which updates the data in the pid file.
If the port management genserver crashes, the process is killed by the loaded monitoring, and the genserver is immediately restarted by the domain supervisor.
If the domain is deleted, monitoring stops the process.
If the node is closed, it has time to stop child processes.
If the node crashes, on the next domain startup it cleans up extra processes based on pid files. If there are no processes but files exist, it tries to kill the process by identifier. The startup command is not verified.
+
If the corresponding `mservice` entity changes, domain microservice synchronization begins no later than 1 second later. The synchronization process starts every 60-65 seconds even without changes.
If a crash occurs during an attempt to start processes, the domain retries synchronization after 10 seconds.
If synchronization completes with an error, the domain retries microservice synchronization after 10-15 seconds.
If synchronization skips some microservices (archive not downloaded, not found, checksums do not match), the domain retries microservice synchronization after 20-25 seconds.
On errors, some microservices may have started and some may not, so a forced stop is called before start.
+
Newly created entities go through site filtering, data preparation, attachment archive lookup and unpacking, and starting the service process according to the entity settings.
Deleted entities are stopped, the process terminates, the pid file is removed, and data from the unpacked archive directory is deleted.
+
During synchronization, an entity is considered changed if any field has changed, except the `ext` field.
Uploading a new archive to the attachment is also considered an entity change because file metadata is written to the `opts.attachment_info` field.
Changed entities cause the microservice process to stop (`kill`, without cleaning the unpacked archive directory) and then start again.
On every start/restart, the presence of a zip archive attachment on the entity is checked. If the unzip command cannot unpack it, the attachment is considered broken and the entity is excluded from loading.
If no archive is attached to the entity (empty object in `opts.attachment_info`), the entity is analyzed.
If an archive is attached to the entity but is not yet present on the node, the entity is removed from the active list until the next synchronization iteration (no later than 20 seconds).
If an archive is attached to the entity but its data does not match the attachment information in the entity, the entity is removed from the active list until the next synchronization iteration (no later than 20 seconds).
If the entity archive has not changed (its data matches the information in `/var/lib/era/_workdir/<NODE>/mservices/<DOMAIN>/<ENTITY_NAME>.archive-info.json`), no re-unpacking is performed (even if the directory was manually damaged).
If the entity archive has changed (its data differs from the information about the already unpacked archive), the service directory is deleted, the archive is unpacked again, and the `*.archive-info.json` file is created.
If the entity archive is deleted, the entity is removed from the active list until the next synchronization iteration, processes are terminated, and the microservice directory is cleaned.
+
Untouched entities continue to run without stops.
+
The microservice process must construct the full access URL itself, choose the connection protocol and authorization method, and authorize the connection under an integration channel token or a system user. These parameters must be passed to it in `cmdline` / `cmdparam` of the mservice entity.

Table 1. System characteristics

Code

msvc

Operation mode

Service

Redundancy mode

Active-Active

Site types

Any

Layer

Business logic

Placement

Internal

State preservation and recovery on restart

-

Application

era_msvc

Managed application

Defined by elements of the mservices collection

Parameters

Table 2. Parameters
Name Type Default Description

name

str

required

Name. May consist of Latin letters and digits and must start with a letter.

roletype

str

required

Role type. Possible values: "msvc".

ext

json

empty

Additional role options. Contains a JSON object or list.

enabled

bool

empty

Role activity flag. When set to false, the role does not participate in validation and is not started.

limit_of_cores

int

empty

Limit on the number of CPU logical cores used. Default: 0 - unlimited.

logging_default_level

int

empty

Default logging level set specifically for the role instance (microservice type). More

allow_divergence

bool

false

Flag allowing parameter differences in roles of the same group. Default: false - not allowed.

roleid

int

required

Role identifier. Unique across the entire system, regardless of site or server.
Cannot be changed after assignment. An integer from 1 to 9999

separate

bool

required

Flag indicating whether the role is allocated to a separate node.

sections

array<str>

List of sections in which the instance participates.
A section can be specified in the properties of the mservice entity, and then only instances that have the specified section in this field are involved in its execution.
The exception is when the current site has no msvc instance serving the section specified in the mservice entity. In this case, all msvc instances on the current site are allowed to serve it.

order

int

0

Leadership priority. Used for microservices with active-passive mode enabled.

Configuration example

Configuration management is performed in an application available to master domain administrators. The application hides the full configuration content, but it is still available through the API.

The configuration contains a section describing all instances of all roles. Parameters are defined for each specific role instance.

Node example
{
  "name": "msvc1",
  "roletype": "msvc",

  "roleid": 11320,
  "separate": true
}