Migrating Hyperledger Fabric 1.4.x to 2.2.x
Hyperledger Fabric migration to 2.2.x involves migrating your network, data and chaincode. This blog details out the changes, approach, learnings and challenges.
Overview
Hyperledger Fabric has recently released its version 2.3.1 and also released patches of its LTS releases v2.2 (2.2.3) and v 1.4(1.4.12). The 2.2 version offers great benefits over the 1.4 version.
We recently migrated a solution previously using 1.4 version to the 2.2 version.
In this blog we shall look at
- some of the new exciting features,
- three step approach to migration,
- major challenges faced and
- touch upon migration of your chaincode.
I plan to write a separate blog to describe the detailed approach and learnings from the exercise.
Any new applications/projects taken up with Hyperledger Fabric should utilize version 2.2 due to its Long term support commitment and enhanced features that it offers.
Major Changes in Newer Version(v2.2.x)
Major changes include support for new application and privacy patterns, and better governance of the Chaincode. Some of them are listed below
No Single owner of Chaincode
In the previous versions, any organization could initialize a Chaincode on the channel if they had the necessary access. However since 2.x, a separate Chaincode lifecycle policy is maintained which must be met before any Chaincode could be committed on the channel.
Validate as per your need
Organizations, now only have to agree on the Chaincode function signatures. If the Chaincode signatures match, and the consensus is achieved on the results/outputs from the functions, then the write-set is accepted and transaction can be committed on the ledger. Thus, if you want to modify Chaincode to introduce validations, you deem necessary, you can do that without impacting others using the same Chaincode.
Local Cache Reads for World State
With 2.x, your world state db implemented using CouchDB allows using fast local cache reads.
Reduced Docker Container sizes
Hyperledger fabric docker container images are built on top of Alpine Linux, which follows minimalistic approval and provides reduced size containers. Alpine Linux is also considered more secure.
Migrating From 1.4.x to 2.2.x
If you are already on 1.4.x, and find 2.x more suitable or preferrable, then you can migrate using the following Three Step approach:
Prepare
- Prepare your Network
- Take backup of configuration, ledger and MSPs - Prepare your Code
- Due to the enhancements and structural changes between version 1.4 and 2.2, it becomes difficult to use the smart contracts and application written for 1.4 to run smoothly over 2.2. Refer the ‘Migrate your Chaincode’ section below for details. - Migrate
- Upgrade your orderer instances, one at a time.
- Update your peers, one at a time. - Soft-Switch
- It is called Soft-Switch because you don’t need to bring your network down to make the switch.
- Update the capabilities of your orderer and peers. (Ensure that your orderer and peers are all upgraded before your move to upgrade the capabilities). - Train your Operations team
- Provide appropriate training to the operations team, to bring them up to speed on the new features and updates on the newer version. - Migrate your Chaincode
- If you plan to migrate a project from Fabric 1.4.x to 2.2.x, and your project is more than a simple PoC, then higher chances are that you will have to migrate your Chaincode and write your clientSDK wrapper to continue using the features that were previously available out-of-the-box from the 1.4.x clientSDK wrapper.
Main Challenges faced in migration
- Retraining of the operations team on newer version due to the administrative differences between the releases.
- Chaincode structural changes and features deprecated & since removed in the newer version reduces the compatibility with the code written in previous version.
- The opensource Hyperledger endorsed Fabric Client SDK wrapper, which was previously available for 1.4 version which allowed extended features without explicit need to write code is not compatible with the newer version.
— Hyperledger has released newer version of its client SDK but it requires developers to write the wrapper code to include the extended features. For example, the feature to fetch a block from the ledger has been introduced recently and was not available initially. Many such features are still not available. - No more fabric token. Fabric previously provided ‘fabric token’ which was utilized by the developers to validate the authentication of the user, is not available in the new client SDK.
- Chaincode lifecycle policy by default requires the Chaincode to be approved by the nodes. Thus, if left as is causes additional steps to be performed every time a Chaincode is modified and thereby increasing the dev/test overhead.
Approach to Migrating your Chaincode
Identify
- Identify missing features from ClientSDK that you would need.
- Identify the Chaincode changes required. This may be needed due to change is SHIM packaging, removal of Logging, Chaincode function definition signatures changes.
Prepare
- Write code in your clientSDK wrapper to account for the missing features. The quantum of changes depends on whether your clientSDK wrapper was from 1.4.x or if you continued using the older client sdk conventions.
- Convert your Chaincode to latest structure.
Test
- Perform necessary smoke and regression testing.
Conclusion
Hyperledger Fabric has taken into considerations to ensure that your Network can be easily migrated from 1.4.x in rolling fashion to the latest version. However, you need to ensure that you use best methodology and work out your approach before your start converting your previous version Chaincode to the latest one.
