z2-Environment

h1. How to configure and use the Gateway module

(work in progress)

The Gateway implements a "zero-downtime-upgrade" feature in Z2. Specifically, it uses the worker process management of Z2 in conjunction with an intermediate reverse proxy style Web handler to implement the following feature: 

Upgrading a stateful Web application, i.e. a Web application that stores user data in its HTTP session typically implies downtime, and if the session state is not serializable and persisted during the upgrade, it does additionally imply that user state gets lost and typically that users need to log on again.

Using the Gateway, running sessions may be preserved and worker resources may still be assigned on the current software revision for as long as there are running sessions during a node upgrade and until all sessions have been terminated. The typical application of this feature is to roll out functional and user interface corrections without interrupting users. Users can switch over to post-upgrade software by terminating their session (e.g. via a log out) and starting a new one (e.g. by logging in again).

*Note:*

* This feature is relatively new and before you use it in production, you should have carefully tested your scenario.

* There are natural limitations to this feature. Upgrades that change the structure or semantics of persisted data or other resources that are shared across nodes cannot be handled this way.

h2. Trying a sample

As described in [[How to run a sample]] please clone the repository "z2-samples.gateway":http://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-gateway and import the contained *environment* module. This module is holding a Gateway configuration as described below. After re-starting your Z2 installation, try the following:

1. Open a browser and navigate to http://localhost:8080/z_gateway. Use (by default) user "z*" with password "z".

You should see this:

!gateway1.png!

2. Open another browser window and navigate to http://localhost:8080/adm (same user). Choose the group "Workers" and update.

Check for the current worker process and their state. You should see something like this:

!admin1.png!

Both web applications application create a HTTP session. Now go back to the Gateway user interface and press "Detach environment/webWorker@0 and sync". On your console you will see that another worker process started (called environment/webWorker@1) and if you update the worker list in the admin interface you should see something like this:

!admin2.png!

That is: One worker was _detached_ while another one is in state _started_.

If you now refresh the Gateway user interface you will see that it is still served from *environment/webWorker@0*. Press "log off". You should find that it now switched to *environment/webWorker@1*.

Let's recap: Now we have a session on *environment/webWorker@0* via the admin user interface and one one *environment/webWorker@1* via the Gateway user interface.

3. Detach *environment/webWorker@1* by clicking "Detach environment/webWorker@1 and sync" on the Gateway user interface.

When checking the worker list you will now see something like this: 

!admin3.png!

h2. Administrator flow

h2. Details on the implementation

* Running web worker processes may be "detached". Meaning that they do not receive synchronization updates and hence stay on the software versions they currently have. Also, a detached worker process 

tbd