Your distributed blockchain application must anticipate and support changes made to the platform components. Focusing on the components we have created and launched in our sample trade network, these include the Fabric peer, orderer, and CA (or MSP.) Just like the application chaincode is subject to change to account for bugs and new requirements, so can the platform change over time. Fabric, since its genesis in late 2015, has changed many times, each change being pushed as an upgrade with a new version, and the current version is 1.1. Whenever a platform component gets upgraded, you need to replace those components in your running system without disrupting the life cycle of your application. In this section, we will demonstrate how to do that.
You can run your network components in different configuration, one way using docker containers, which is the approach we have demonstrated in this book. To upgrade platform components running in docker containers, the first thing you need to do is generate new images for the various components. This can be done either by downloading the relevant images from Docker Hub or downloading the source and building the images natively using make docker; the latter approach is what we have followed in this book. To see the entire list of Hyperledger Fabric images downloaded to your system, you can run something as follows:
docker images | grep hyperledger/fabric
You will see a long list of image entries, most of them duplicated, with the latest tag being a pointer to one of the images with a specific tag name. Since our docker-compose YAML files in the network folder (docker-compose-e2e.yaml, base/docker-compose-base.yaml, and base/peer-base.yaml) depend only on the images for fabric-peer, fabric-orderer, and fabric-ca, let us examine just those:
hyperledger/fabric-peer latest f9224936c8c3 2 weeks ago 187MB hyperledger/fabric-peer x86_64-1.1.1-snapshot-c257bb3 f9224936c8c3 2 weeks ago 187MB hyperledger/fabric-orderer latest 5de53fad366a 2 weeks ago 180MB hyperledger/fabric-orderer x86_64-1.1.1-snapshot-c257bb3 5de53fad366a 2 weeks ago 180MB hyperledger/fabric-ca latest 39fdba61db00 2 weeks ago 299MB hyperledger/fabric-ca x86_64-1.1.1-snapshot-e656889 39fdba61db00 2 weeks ago 299MB
You will see something like the preceding when you run the docker images command. The Docker images listed here were built natively from the release-1.1 branches of the Fabric and Fabric CA source code. If you download a different version of the source code and build the images using make docker, you will see a third image entry for each of the preceding components, and your latest image tag will be linked to the one that you just created.
We will go through an following example where the trade network's orderer and peers are upgraded. We will leave upgrading fabric-ca as an exercise to the user. To do this in a running application, you will need to perform the following sequence of steps:
- Download or build new versions of platform component images
- Stop the components
- (Optional) make a backup of your ledger contents for safety
- Stop the running chaincode containers
- Remove the chaincode container images from your system
- Ensure that the image tags referenced in the docker-compose YAML files are linked to the new versions of the components
- Start the components
You can also choose to stop, upgrade, and start each component in turn rather than all at once. You will need to stop all incoming requests to the system while this upgrade is going on, which should be a simple matter of shutting down your application web servers.
There is sample code to upgrade our trade network in this manner in the upgradeNetwork function in network/trade.sh in the code repository. Here, we assume that the user will either:
- Pass the new image tag (such as x86_64-1.1.1-snapshot-c257bb3 in the preceding list) as a command-line parameter using the -i switch, or
- Link the latest tag to the new image
Before calling the function. Now we must stop the orderer and peers:
COMPOSE_FILE=docker-compose-e2e.yaml ...... COMPOSE_FILES="-f $COMPOSE_FILE" ...... docker-compose $COMPOSE_FILES stop orderer.trade.com ...... for PEER in peer0.exporterorg.trade.com peer0.importerorg.trade.com peer0.carrierorg.trade.com peer0.regulatororg.trade.com; do ...... docker-compose $COMPOSE_FILES stop $PEER ...... done
As we can see preceding code, the docker-compose YAML file used to start the network must be used to stop individual components too.
Once the containers are stopped, we can choose to backup the ledger data as follows:
LEDGERS_BACKUP=./ledgers-backup mkdir -p $LEDGERS_BACKUP ...... docker cp -a orderer.trade.com:/var/hyperledger/production/orderer $LEDGERS_BACKUP/orderer.trade.com ...... for PEER in peer0.exporterorg.trade.com peer0.importerorg.trade.com peer0.carrierorg.trade.com peer0.regulatororg.trade.com; do ...... docker cp -a $PEER:/var/hyperledger/production $LEDGERS_BACKUP/$PEER/ ...... done
The contents of the ledger on the peers as well as the orderer are now backed up to your local machine in the ledgers-backup folder.
Now we should remove all the chaincode images because new ones need to be created by the new fabric-peer images, and the presence of old images will block that creation:
for PEER in peer0.exporterorg.trade.com peer0.importerorg.trade.com peer0.carrierorg.trade.com peer0.regulatororg.trade.com; do
......
CC_CONTAINERS=$(docker ps | grep dev-$PEER | awk '{print $1}')
if [ -n "$CC_CONTAINERS" ] ; then
docker rm -f $CC_CONTAINERS
fi
CC_IMAGES=$(docker images | grep dev-$PEER | awk '{print $1}')
if [ -n "$CC_IMAGES" ] ; then
docker rmi -f $CC_IMAGES
fi
......
done
Now we can restart the stopped orderer and peer containers. When running docker-compose up, the orderer and peer containers will be started with the new image:
docker-compose $COMPOSE_FILES up --no-deps orderer.trade.com ...... for PEER in peer0.exporterorg.trade.com peer0.importerorg.trade.com peer0.carrierorg.trade.com peer0.regulatororg.trade.com; do ...... docker-compose $COMPOSE_FILES up --no-deps $PEER ...... done
You can run the entire upgrade process in one shot by running the script in either of the following ways:
./trade.sh upgrade [-i <imagetag>]
If the <imagetag> is not specified, it will default to latest, as mentioned earlier.
You can now continue to run your distributed trade application. Note that platform changes may also be accompanied by changes in chaincode and SDK API, which may necessitate an upgrade to your chaincode or your middleware or both. As we have demonstrated examples of those in previous sections, the reader should not be fully equipped to upgrade both the application and the underlying blockchain platform at any point during the application's and network's life cycle.