Migrating from Zato 1.1 to 2.0

Overview

Migrating from 1.1 to 2.0 is a process that requires a full shutdown of an environment. Depending on the number of components involved, the steps take at least an hour if performed the first time.

Users are highly recommended to carry them out on side environments first to become familiar with all the aspects involved.

Please visit the support options page if any sort of assistance is required.

The steps are executed in this order:

Stopping components

  • On each operating system Zato 1.1 runs, switch current user to zato, for instance:

    $ sudo su - zato
    $ whoami
    zato
    $
  • Use zato stop to stop each and every Zato 1.1 component in the environment being migrated over to 2.0 - stop the web-admin console, the load-balancer and all the servers.

  • For each of the components stopped, use zato info to confirm that it is version 1.1 and that it is not running anymore - consult the component_details and component_running rows, such as below:

    $ zato info /opt/zato/cluster1
    
    +--------------------------------+-----------------------------------------------+
    |              Key               |                     Value                     |
    +================================+===============================================+
    | component_details              | {"created_user_host": "zato@myhost",          |
    |                                | "version": "1.1", "component": "SERVER",      |
    |                                | "created_ts": "2014-11-13T07:57:52.704605"}   |
    +--------------------------------+-----------------------------------------------+
    | component_full_path            | /opt/zato/cluster1/server1                    |
    +--------------------------------+-----------------------------------------------+
    | component_host                 | myhost/myhost                                 |
    +--------------------------------+-----------------------------------------------+
    | component_running              | False                                         |
    +--------------------------------+-----------------------------------------------+
    | current_time                   | 2014-11-13T12:26:50.572272                    |
    +--------------------------------+-----------------------------------------------+
    | current_time_utc               | 2014-11-13T11:26:50.572293                    |
    +--------------------------------+-----------------------------------------------+
    | master_proc_connections        | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_create_time        | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_create_time_utc    | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_name               | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_pid                | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_username           | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_workers_no         | None                                          |
    +--------------------------------+-----------------------------------------------+
    | master_proc_workers_pids       | None                                          |
    +--------------------------------+-----------------------------------------------+
    

Removing 1.1

On each system Zato 1.1 is installed on, execute the following steps:

  • Back up any configuration stored in /opt/zato that may be still needed after migrating to 2.0

  • As root or an equivalent user, use the operating system's tools, such as apt-get to remove the 'zato' package containing Zato 1.1

  • Issue the following command, removing /opt/zato from the system

    $ sudo rm -rf /opt/zato

Upgrading Redis to 2.8.4+

Zato 2.0 requires Redis 2.8.4 or newer.

Depending on the exact OS version used, Redis needs to be installed from additional repositories, such as:

  • Remi for RedHat/CentOS (direct links to packages - 6.x and 7.x)
  • PPA for Ubuntu
  • DotDeb for Debian

Installing binaries

  • As root or an equivalent user, install Zato 2.0 on each operating system any Zato component is on.

  • Switch current user to zato.

  • Confirm the zato --version command returns 2.0, such as below. Note that the exact sub-release and revision change with time and may differ. In the example below it's important for the command to return Zato 2.0 followed by any sub-release and revision number.

    $ zato --version
    Zato 2.0.8.rev-050c6697
    $

Upgrading ODB schema

  • Log on to any system 2.0 binaries have been installed to.

  • Switch current user to zato.

  • Open /opt/zato/2.0/alembic.ini in a text editor and find the sqlalchemy.url key.

  • Update the key so it contains the information on how to connect to the environment's ODB. For instance, if:

    • The database is on PostgreSQL
    • Username is zatouser1
    • Password is d0f836f96e6441
    • DB host is 10.19.32.17
    • DB port is 5432
    • DB name is zatodb1

    the key should read:

    sqlalchemy.url = postgres://zatouser1:d0f836f96e6441@10.19.32.17:5432/zatodb1
  • Save the file and close the editor.

  • Change directory to /opt/zato/2.0/ and run the following command:

    $ ./bin/alembic upgrade head
    [snip output]
    $
  • Confirm the ODB has been suceessfully upgraded by running the following command. The expected output will list connection details and end with 0027_e139a019 -> 0028_ae3419a9 (head), gh323 http_soap migration

    $ ./bin/alembic current
    [snip cnx details] 0027_e139a019 -> 0028_ae3419a9 (head), gh323 http_soap migration
    $

Running zato migrate

  • Run zato migrate against each of the components running in a given operating system. Suppose there are 4 components in the following directories:

    • /opt/zato/uat/load-balancer
    • /opt/zato/uat/web-admin
    • /opt/zato/uat/server1
    • /opt/zato/uat/server2

    There will be 4 invocations of zato migrate, as below:

    $ zato migrate /opt/zato/uat/load-balancer
    Migrated /opt/zato/uat/load-balancer from 1.1 to Zato 2.0.8.rev-050c6697
    $
    
    $ zato migrate /opt/zato/uat/web-admin
    Migrated /opt/zato/uat/web-admin from 1.1 to Zato 2.0.8.rev-050c6697
    $
    
    $ zato migrate /opt/zato/uat/server1
    Migrated /opt/zato/uat/server1 from 1.1 to Zato 2.0.8.rev-050c6697
    $
    
    $ zato migrate /opt/zato/uat/server2
    Migrated from /opt/zato/uat/server2 1.1 to Zato 2.0.8.rev-050c6697
    $

Starting components

  • Use zato start to start each and every of the newly migrated Zato 2.0 components in the environment migrated over from 1.1 - start the web-admin console, the load-balancer and all the servers.

  • For each of the components start, use zato info to confirm that it is version 2.0 now and that it is running - consult the component_details and component_running rows, such as below:

    $ zato info /opt/zato/cluster1
    
    +--------------------------------+----------------------------------------------------+
    |              Key               |                       Value                        |
    +================================+====================================================+
    | component_details              | {"created_user_host": "zato@myhost", "version":    |
    |                                | "Zato 2.0.8.rev-050c6697", "component":            |
    |                                | "SERVER", "created_ts":                            |
    |                                | "2015-01-29T17:39:53.351901"}                      |
    +--------------------------------+----------------------------------------------------+
    | component_full_path            | /opt/zato/cluster1/server1                         |
    +--------------------------------+----------------------------------------------------+
    | component_host                 | myhost/myhost                                      |
    +--------------------------------+----------------------------------------------------+
    | component_running              | True                                               |
    +--------------------------------+----------------------------------------------------+
    | current_time                   | 2014-11-24T16:24:35.378779                         |
    +--------------------------------+----------------------------------------------------+
    | current_time_utc               | 2014-11-24T15:24:35.378794                         |
    +--------------------------------+----------------------------------------------------+
    | master_proc_connections        | {'LISTEN': [{u'to': None, u'from':                 |
    |                                | u'127.0.0.1:17010', u'formatted':                  |
    |                                | u'127.0.0.1:17010'}]}                              |
    +--------------------------------+----------------------------------------------------+
    | master_proc_create_time        | 2015-01-29T19:19:28.920000                         |
    +--------------------------------+----------------------------------------------------+
    | master_proc_create_time_utc    | 2015-01-29T18:19:28.920000+00:00                   |
    +--------------------------------+----------------------------------------------------+
    | master_proc_name               | gunicorn:                                          |
    +--------------------------------+----------------------------------------------------+
    | master_proc_pid                | 6662                                               |
    +--------------------------------+----------------------------------------------------+
    | master_proc_username           | zato                                               |
    +--------------------------------+----------------------------------------------------+
    | master_proc_workers_no         | 2                                                  |
    +--------------------------------+----------------------------------------------------+
    | master_proc_workers_pids       | [6670, 6672]                                       |
    +--------------------------------+----------------------------------------------------+
    | worker_6670_connections        | {'ESTABLISHED': [{u'to': u'127.0.0.1:6379',        |
    |                                | u'from': u'127.0.0.1:51850', u'formatted':         |
    |                                | u'127.0.0.1:51850       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51852', u'formatted':         |
    |                                | u'127.0.0.1:51852       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51851', u'formatted':         |
    |                                | u'127.0.0.1:51851       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51846', u'formatted':         |
    |                                | u'127.0.0.1:51846       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51849', u'formatted':         |
    |                                | u'127.0.0.1:51849       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51848', u'formatted':         |
    |                                | u'127.0.0.1:51848       ->                         |
    |                                | 127.0.0.1:6379'}], 'LISTEN': [{u'to': None,        |
    |                                | u'from': u'127.0.0.1:17010', u'formatted':         |
    |                                | u'127.0.0.1:17010'}]}                              |
    +--------------------------------+----------------------------------------------------+
    | worker_6670_create_time        | 2014-11-24T16:19:31.690000                         |
    +--------------------------------+----------------------------------------------------+
    | worker_6670_create_time_utc    | 2014-11-24T15:19:31.690000+00:00                   |
    +--------------------------------+----------------------------------------------------+
    | worker_6672_connections        | {'ESTABLISHED': [{u'to': u'127.0.0.1:6379',        |
    |                                | u'from': u'127.0.0.1:51855', u'formatted':         |
    |                                | u'127.0.0.1:51855       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51853', u'formatted':         |
    |                                | u'127.0.0.1:51853       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51854', u'formatted':         |
    |                                | u'127.0.0.1:51854       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51856', u'formatted':         |
    |                                | u'127.0.0.1:51856       ->                         |
    |                                | 127.0.0.1:6379'}, {u'to': u'127.0.0.1:6379',       |
    |                                | u'from': u'127.0.0.1:51847', u'formatted':         |
    |                                | u'127.0.0.1:51847       ->                         |
    |                                | 127.0.0.1:6379'}], 'LISTEN': [{u'to': None,        |
    |                                | u'from': u'127.0.0.1:17010', u'formatted':         |
    |                                | u'127.0.0.1:17010'}]}                              |
    +--------------------------------+----------------------------------------------------+
    | worker_6672_create_time        | 2014-11-24T16:19:31.730000                         |
    +--------------------------------+----------------------------------------------------+
    | worker_6672_create_time_utc    | 2014-11-24T15:19:31.730000+00:00                   |
    +--------------------------------+----------------------------------------------------+
    

(end of steps)