zato enmasse

Overview

Enmasse is a command line tool that automates deployment of Zato configuration, such as REST or AMQP connections, scheduler and cache definitions or any other object.

• During development, one usually uses the Dashboard GUI to define new elements, i.e. it is usually convenient to fill out a form to have a new REST channel available.

• When a solution, or an incremental part of it, is ready for wider testing, enmasse is used to export it from the development server and to import it to a test server.

• Afterwards, the same enmasse export file can be used to configure production servers.

• The workflow loop now returns to developers who keep using Dashboard to add new server elements

• All of the export and import steps can be part of CI/CD pipelines that automate the provisioning of Zato environments

Anything that can be declared with the Dashboard GUI can be also done with enmasse. For instance, in the screenshot below a new REST channel is being defined.

Next, enmasse can be used to export such a channel to a YAML or JSON file.

[...]

channel_plain_http:
  - cache_expiry: 0
    cache_name:
    is_rate_limit_active: false
    match_slash: true
    name: "My REST Channel"
    url_path: "/api/my/rest/channel"
    service: "pub.zato.ping"

[...]

Such export files can be stored in a git repository. Iteratively, developers add new definitions to the file based on the current state of their work. Ultimately, the file will contain everything that is needed to configure a particular project or solution.

• Note that enmasse will not export any passwords from servers. However, it is always possible to add passwords to enmasse files in user-defined installation scripts.

A common technique is to specify passwords as below - before enmasse runs, a simple sed invocation changes the placeholders into actual passwords.

[...]

name:     "My SQL Connection"
password: "@@CONN_PASSWORD@@"

[...]

• It is possible to use environment variables in enmasse files, using the syntax as shown below. The actual values will be read from the environment by Zato servers server when they receive a file with configuration to import.

• Usually, the only modifications needed in an enmasse file are adding placeholders such as the one above, changing IP addresses or modifying usernames. Note also that an enmasse file will contain various internal pieces of information - do not change it, they are need for enmasse to import such a file back. An export file may also contain objects that you do not need, e.g. extra channel definitions not required in a particular project - feel free to remove them as needed.

• If a multi-server cluster, it suffices that one server import an enmasse file. It will sychronize automatically with all the other servers in the cluster.

• An enmasse file contains configuration only, it does not contain services that the configuration may depend on. Any such services need to be deployed before enmasse runs to import a file.

Usage examples

$ zato enmasse --export-odb /path/to/server/
[...]
Data exported to ./zato-export.yml
$

$ zato enmasse --import     \
  --replace-odb-objects     \
  --input ./zato-export.yml \
  /path/to/server/
[...]
$

Read more

A separate chapter discusses how to deploy services and other code