Overview
Fabric workers are constantly monitoring for new workers to enter the Fabric. When this happens, a process starts to ensure that all of the workers inside of the fabric run on the same version of the Fabric software. This includes all of the Fabric software, configuration files, far files and Fabric Applications. This allows a fabric administrator to easily upgrade an entire fabric without having to touch every machine.
The files with the highest version numbers are considered to to be the latest. A machine that has newer fabric software, but older configuration files or Fabric Applications, will deploy the newer Fabric software into the rest of the fabric, and then receive the latest configuration files and Fabric applications. This way all machines will get synced up, and everyone will have the latest software.
By default a fabric is installed on the 239.255.0.1 mcast address. It is highly recommended that you change this address to something else. Otherwise you run the risk of mistakenly updating a production fabric by installing a test version of the Fabric software. This fabric-address value is located in the addr.cfg.
 | What about this fabric MCAST address?
Each fabric is assigned a unique MCAST address. Fabric clients and utilities (like Log Monitor and Fabric Control) use this MCAST address to communicate with the fabric. This address defaults to 239.255.0.1, but can be changed by setting the fabric-address property in the addr.cfg file that is deployed to all fabric workers. The fabric MCAST address specified by clients and utilities must match the fabric-address entry in the addr.cfg or 239.255.0.1 if using the default. As you go through command and code samples, please be sure to use the correct fabric MCAST address for your installation. |
Upgrade Options
To upgrade a version 3.7 fabric to version 3.8, you have a few of options:
For the examples below, we will be using a production fabric running on the 239.255.0.99 address.
Upgrade an Existing worker
Since we are assuming that your fabric is running transactions, you must stop the fabric services on this worker prior to upgrading it to ensure that the worker is stopped gracefully. Next, you will need to uninstall and then reinstall the Fabric software on that particular box. The steps below will walk you through this process.
 | Uninstalling the fabric software on a machine will remove the entire fabric system directory. You will need to reconfigure the addr.cfg. |
To get a list of ip addresses that are in the fabric
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin query all
192.168.0.9 up
192.168.0.17 up
192.168.0.20 up
192.168.0.23 up
192.168.0.27 up
Suppose the box that we want to upgrade is on 192.168.0.27. Issue a fabric_ctl stop to gracefully stop all requests currently processing on this worker. Note: the fabric_keeper and fabric_system_service services/daemons will still be running on this machine.
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin stop 192.168.0.27
Now uninstall the Fabric software on this worker. On win32 platforms, you can remove it by going to "Add Remove Programs" and removing the "Appistry EAF" software. On unix you will want to use rpm -e.
$ sudo rpm -e appistry-eaf
The version 3.8 installers have logic to shutdown any remaining fabric services that are running when you uninstall. You might want to check to make sure everything is shutdown before installing the newer version. For win32, you can look for any running services that begin with 'Appistry'. On unix, run ps eaf | grep fabric | grep -v grep and issue a kill -TERM to any running processes.
You are now in a state where you can follow the directions for "Installing on a new worker".
Installing on a new worker
Follow the Installing the Fabric procedures for your platform. If you have not done so already, configure your worker to use the fabric-address for the Fabric you want to upgrade. If you are unsure how to change the address of your Fabric, you can find more information here. When the worker starts up on the intended fabric-address, it will automatically upgrade the other workers in the Fabric.
To check to make sure everything is upgraded, you can use fabric_ctl to check the version of all of the workers.
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin fabric-version fabric all
Version 3.8.0.12: 5 Workers
If you see some workers on the older version, you may need to wait a little longer for all of the workers to cycling. You can use log_monitor to view the activity.
Deploying an upgrade file
Another potential option for upgrading is to get an upgrade file from Customer Support
or from the Peer2Peer download site. By simply deploying a fabric.upgrade file, the fabric will do a rolling deployment, and upgrade the fabric workers in place.
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin deploy fabric3.8.0.12.upgrade
Recommended upgrade procedure in a production environment
For production environments, we recommend setting up a small Fabric with the newer software and test things out in isolation. Once everything is confirmed to be working as expected, switch those machines over to the same address of the production Fabric and the production Fabric will automatically be updated.
Partition off a test Fabric
Move a subset of your production Fabric workers to a different fabric-address for testing. Grab the existing addr.cfg, edit it and configure a new fabric-address, and deploy to a subset of machines.
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin get addr.cfg
addr.cfg: received
$ cat addr.cfg
fabric-address=239.255.0.99
Use you favorite text editor and change the address to something else. For this example we will change it to 239.255.0.10.
$ cat addr.cfg
fabric-address=239.255.0.10
Now deploy the new addr.cfg to a subset of machines. We'll pick two from our example above...
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin put-addr 192.168.0.23 192.168.0.27
Once the addr.cfg deploys and the workers restart, they will be running on the new 239.255.0.10 Fabric.
$ fabric_ctl -d239.255.0.10:30000 -ufabric-admin/fabric-admin query all
192.168.0.23 up
192.168.0.27 up
Upgrade the test Fabric
Now you can follow one of the upgrade paths listed above, performing the actions on the new 239.255.0.10 Fabric. Use fabric_ctl fabric-version to verify that they upgraded.
$ fabric_ctl -d239.255.0.10:30000 -ufabric-admin/fabric-admin fabric-version fabric all
Version 3.8.0.12: 2 Workers
Verify everything works
Once the test fabric is upgraded, test your existing Fabric apps to make sure everything works. Verify that everything upgraded. Point some of your client applications at the upgraded Fabric and confirm all is well.
Merge the test Fabric back into production
Once you are happy, and are ready to upgrade the production fabric, simply change the fabric-address back to the production address (239.255.0.99 in our example) and deploy it to the test fabric.
$ fabric_ctl -d239.255.0.10:30000 -ufabric-admin/fabric-admin put-addr 192.168.0.23 192.168.0.27
And again, once everything cycles, verify all workers are upgraded:
$ fabric_ctl -d239.255.0.99:30000 -ufabric-admin/fabric-admin fabric-version fabric all
Version 3.8.0.12: 5 Workers
Notes
| These upgrade procedures only apply installs that include the worker install.
If you have installed the administrator-only or developer-only(sdk) installations on a stand alone worker, these upgrade procedures will not upgrade the files on those boxes. You will need to uninstall and reinstall those respective files. |
