-
Notifications
You must be signed in to change notification settings - Fork 212
Migration Guide for v1.1.0
Hyperledger FireFly v1.1.0 is the next planned minor release. Although labeled as "minor", it includes significant new functionality around namespaces and plugins, as detailed in FIR-12. As a result, upgrading an existing FireFly environment from any prior release may require special steps depending on the functionality used.
Significant care has been taken to ensure that backward-compatibility is preserved, and most existing environments can be upgraded seamlessly. This document is long due to the number of possible permutations, but the goal is that the majority of users will only require minimal extra steps during upgrade.
However, if you wish to upgrade an existing environment with the least possible chance of any errors or downtime, this guide will attempt to lay out the required steps for all possible cases.
Upgrade to latest v1.0.x patch release
Before upgrading to v1.1.0, it is strongly recommended to upgrade to the latest v1.0.x patch release (v1.0.3 as of the writing this document). Do not proceed any further in this guide until all nodes are successfully running the latest patch release version.
Fix any deprecated config usage
All items in FireFly's YAML config that were deprecated at any time in the v1.0.x line will be unsupported in v1.1.0. After upgrading to the latest v1.0.x patch release, you should therefore look for any deprecation warnings when starting FireFly, and ensure they are fixed before upgrading to v1.1.0. Failure to do so will cause your config file to be rejected in v1.1.0, and FireFly will fail to start.
Record all namespaces in the config file
Will not affect applications that exclusively use the default namespace.
FireFly v1.0 allowed for the dynamic creation of new namespaces by broadcasting a namespace definition to all nodes. This functionality is removed in v1.1.0. If your network relies on any namespaces that were created via a broadcast, you must add those namespaces to the namespaces.predefined list in your YAML config prior to upgrade. If you do not, they will cease to function after upgrading to v1.1.0 (all events on those namespaces will be ignored by your node).
Identify queries for organization/node identities
Applications that query /network/organizations or /network/nodes will temporarily receive empty result lists after upgrading to v1.1.0, just until all identities have been re-registered (see steps in "After Upgrading"). This is because organization and node identities were broadcast on a global "ff_system" namespace in v1.0, but are no longer global in v1.1.0.
The simplest solution is to shut down applications until the FireFly upgrade is complete on all nodes and all identities have been re-broadcast.
If this poses a problem and you require zero downtime from these APIs, you can proactively mitigate with the following steps in your application code:
- Applications that query the
/network/organizationsmay be altered to also query/namespaces/ff_system/network/organizationsand combine the results (but should disregard the second query if it fails). - Applications that query the
/network/nodesmay be altered to also query/namespaces/ff_system/network/nodesand combine the results (but should disregard the second query if it fails).
Further details on the changes to /network APIs are provided in the next section.
Identify usage of changed APIs
Unlikely to affect most applications, except those using non-default namespaces or other complex configuration.
The primary API change in this version is that the "global" paths beginning with /network and /status have been relocated under the /namespaces/{ns} prefix, as this data is now specific to a namespace instead of being global. At the same time, the API server has been enhanced so that omitting a namespace from an API path will query the default namespace instead. That is, querying /messages is now the same as querying /namespaces/default/messages (assuming your default namespace is named "default"). This has the effect that most of the moved APIs will continue to function without requiring changes. See below for details on the affected paths.
These global routes have been moved under /namespaces/{ns}. Continuing to use them without the namespace prefix will still work, and will simply query the default namespace.
/network/diddocs/{did}
/network/nodes
/network/nodes/{nameOrId}
/network/nodes/self
/network/organizations
/network/organizations/{nameOrId}
/network/organizations/self
/status
/status/batchmanager
These global routes have been moved under /namespaces/{ns} and have also been deprecated in favor of a new route name. Continuing to use them without the namespace prefix will still work, and will simply query the default namespace. However, it is recommended to switch to the new API spelling when possible.
/network/identities - replaced by existing /namespaces/{ns}/identities
/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did}
These global routes have been have been permanently renamed. They are deemed less likely to be used by client applications, but any usage will be broken by this release and must be changed after upgrading.
/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace)
/status/websockets - moved to /websockets
The response bodies of the following APIs have also had fields removed. Any usage of the removed fields will be broken by this release and must be changed after upgrading.
/namespaces - removed all fields except "name", "description", "created"
/namespaces/{ns} - same as above
/namespaces/{ns}/status - removed "defaults"
No special considerations are needed during the upgrade. After performing the steps above, bring FireFly down and replace it with the new v1.1.0 binary, then start it up again.
Ensure nodes start without errors
Ensure that FireFly starts without errors. There will likely be new deprecation warnings for config that was deprecated in v1.1.0, but these are safe to ignore for the moment. If you face any errors or crashes, please report the logs to the FireFly channel on Discord, and return your nodes to running the previous version of FireFly if necessary.
Re-broadcast organization and node identities
Once all nodes in the multiparty network have been upgraded and are running without errors, each node should re-broadcast its org and node identity by invoking /network/organizations/self and /network/nodes/self (or, if your application uses a non-default namespace, by invoking the /namespace/{ns}-prefixed versions of these APIs).
This will ensure that queries to /network/organizations and /network/nodes return the expected results, and will register the identities in a way that can be supported by both V1 and V2 multiparty contracts (see "Upgrading the Multi-Party Contract").
Optional: clean up old token subscriptions
Optional: clean up old multiparty subscriptions
FireFly v1.1.0 includes a new recommended version of the contract used for multi-party systems (for both Ethereum and Fabric). It also introduces a versioning method for this contract, and a path for migrating networks from one contract address to a new one.