Upgrading and deleting deployed nodes

Upgrading nodes from Fabric v1.4 to v2.2

Use the following recommended procedure to upgrade your Fabric v1.4 peer and orderer nodes to v2.2, regardless of whether you are also migrating your v1.4 chaincode to run on Fabric v2.2. Once on v2.2, you can migrate your nodes to v2.4.

Attention: To update to Fabric v2.2, the recommended process (below) adds a new peer, rather than updating an existing peer in place. Adding a new peer avoids the extended time to rebuild CouchDB (if applicable) and downtime when an existing peer is updating. The final step then deletes the replaced peer.

Update your CAs

Update your Certificate Authority (CA) nodes before you upgrade your peer and orderer nodes, as follows:

Attention: Most application solutions do not interact with CAs continually, in which case CAs can be upgraded with no impact to application usage. However, any application flows that use fabric-ca functionality may be unavailable for 1-2 minutes during the update.

1. Using your console, navigate to your Certificate Authority and select the first CA node. Click on upgrade available and select 1.5.5-2 or later.
2. The CA node will restart with the upgrade installed.
3. Repeat the steps for each CA node.

Update your orderers

After updating your Certificate Authority (CA) nodes, update your orderer nodes, as follows:

1. Using your console, navigate to the ordering service and select the first ordering node. Click on upgrade available and select 2.2.10-1 or later. Click through the confirmations dialogs.
2. The node will restart using the 2.2.10-1 (or selected) image. Transaction processing will continue during the node restart, because the remaining four orderer nodes make a quorum. The selected orderer node will be unavailable for 1-2 minutes during the update. ATTENTION!!: If the updating orderer node does not restart and come back online successfully, please contact IBM Support. DO NOT attempt to update any remaining orderer nodes before contacting IBM Support.
3. Repeat the procedure for each remaining orderer node.

Update your peers

After updating both your Certificate Authority (CA) and orderer nodes, update your peer nodes, as follows:

ATTENTION!!: When creating new v2.2 peers using the steps below, selecting 2.2.10-1 is highly recommended - other selectable versions may have chaincode implications.

1. Before upgrading any peer with CouchDB installed, you must rebuild the CouchDB state database from CouchDB v2.x to v3.x. The recommended process is to add a new peer, and then let the database synchronize. This removes the downtime that would occur when upgrading in place. Then continue as follows, for peers both with and without CouchDB:

2. Add a new peer using your console. Do NOT install chaincode on the new peer.

3. Remove the new peer from both peer gossip and service discovery, as follows:

   a) Get the Custom Resource Definition (CRD) of the new peer, by running:

   kubectl get ibppeer -n [NAMESPACE]
   

   b) Back up the CRD: kubectl get ibppeer [IBPPEER_NAME] -n [NAMESPACE] -o yaml > ibppeer_crd_backup.yaml

   c) Edit the CRD: kubectl edit ibppeer [IBPPEER_NAME] -n [NAMESPACE]

   d) Change spec.peerExternalEndpoint: to do-not-set as follows: spec.peerExternalEndpoint: do-not-set

   e) Delete the peer deployment: kubectl get deployment -n [NAMESPACE] and then: kubectl delete deployment [PEER DEPLOYMENT NAME] -n [NAMESPACE]

   f) The peer will restart - then it should not be discoverable by application service discovery. Do NOT update the client connection profiles at this time.

4. Add the new peer to the channel(s) that existing peers are participating in. Do NOT install channel chaincode on the new peer.

5. Let the new peer synchronize its blocks, to the block height of the existing peers.

6. Reenable PEER_GOSSIP on the new peer, as follows:

   a) Get the Custom Resource Definition (CRD) of the new peer, by running: kubectl get ibppeer -n [NAMESPACE]

   b) Back up the CRD: kubectl get ibppeer [IBPPEER_NAME] -n [NAMESPACE] -o yaml > ibppeer_crd_backup.yaml

   c) Edit the CRD: kubectl edit ibppeer [IBPPEER_NAME] -n [NAMESPACE]

   d) Change spec.peerExternalEndpoint to a blank string, using empty quotation marks, as follows: spec.peerExternalEndpoint: ""

   e) Delete the peer deployment: kubectl get deployment -n [NAMESPACE] and then: kubectl delete deployment [PEER DEPLOYMENT NAME] -n [NAMESPACE]

   f) The new peer will restart - then it should begin participating in service discovery and getting new blocks. Application targeting will depend on the connection profile and application logic.

7. Install chaincode on the new peer.

8. Test the new environment by running applications with all peers (original and new) enabled.

9. (Recommended) Test applications by turning off the peer that is being replaced, as follows:

   a) Run: kubectl patch [ibppeer-name] -n [namespace] -p=[{"op": "replace", "path":"/spec/replicas", "value":0}] - type=json

   b) Ensure application continuity with the original peer is NOT running.

10. Delete the original peer.

11. Repeat the prior steps for each peer you are updating.

Upgrading nodes from Fabric v1.4 to v2.4

Upgrading IBM Blockchain Platform nodes directly from Hyperledger Fabric 1.4.x to the latest Fabric version is possible, but deploying a new Fabric 2.2.x peer instead of upgrading is recommended. Fabric installation is done by IBM Blockchain Platform, but can take hours or days depending on the size of the database to be built. See the Fabric documentation on upgrading for more information.

If your Fabric v1.4 nodes use Node.js chaincode, use the following sequence to upgrade these nodes from Fabric v1.4 to v2.4:

1. Deploy new peers with Fabric v2.2
2. Update the Node.js chaincode on these peers to 2.4 shim
3. Install and instantiate the new chaincode
4. Upgrade the peers from Fabric v2.2 to v2.4.

Step one: Back up your ledger (optional)

It is recommended to take regular backups of the persistent volumes of your nodes as part of the normal process of network administration. For example, in our topic on backing up and restoring components and networks, an example schedule is provided which recommends that backups be taken of the ordering nodes and the peers (including the state database of the peer, if using CouchDB) each night.

However, if you are not taking regular backups, it is recommended that you minimally take a backup before attempting to upgrade a node, as it allows for a node to be restored to an earlier running state in cases where the upgrade fails. For information about how to backup your nodes by taking a snapshot of the relevant persistent volumes, check out Taking snapshots.

Step two: Upgrade your nodes one at a time

If you are upgrading both peer and ordering node binaries, it is a best practice to upgrade the ordering nodes first, as ensuring that the ordering nodes (and by extension, the ordering service) is functioning correctly is more important to the health of your network as a whole than the functioning of any particular peer.

The process for upgrading a node is relatively straightforward. First, make sure you are using the console where the node was created. You cannot use the console to update imported nodes. When a node upgrade is available, Upgrade available is visible on the node tile. If Upgrade available does not appear on the tile when it should be there, make sure you have upgraded to the latest version of the console.

You can then update the node:

1. Click on the tile representing the node.
2. The upgrade panel can be accessed either by clicking the Info and usage tab, next to the Upgrade available notice, or the Fabric version box. Clicking either one opens the Upgrade Fabric version side panel.
3. On the Upgrade Fabric version side panel, review the version of your node and the version you are upgrading to. If this is right, click Next.
4. On the next panel, confirm the information and enter the name of the node being upgraded.

The node will be unavailable during the upgrade. The status was turn grey and will read Status unknown or Unavailable. When the upgrade has completed, the status will turn green and be Ready. If the upgrade fails and the node lapses into an unrecoverable state, follow the instructions for Restoring nodes from a snapshot.

It is a best practice to only upgrade one node of each type at a time. In other words, if you need to upgrade both peers and ordering nodes, you can start a single peer upgrade and a single ordering node upgrade at the same time. However, do not attempt to upgrade multiple peers or multiple ordering nodes at the same time, as this threatens the availability of your components.

It is not possible to upgrade an ordering node if any node in your ordering service is down for any reason. Coordinate with all of the administrators of your ordering service before attempting to upgrade.

Step three: Update SDKs and smart contracts

It is a best practice to upgrade your SDK to the latest version as part of a general upgrade of your network. While the SDK will always be compatible with equivalent releases of Fabric and lower, it might be necessary to upgrade to the latest SDK to leverage the latest Fabric features. Also, after upgrading, it's possible your client application may experience errors. Consult the your Fabric SDK documentation for information about how to upgrade.

Although support for Fabric 2.0 networks was added to the platform, you can still run your existing smart contracts on your peers that run a v1.4 image on a channel with an application capability level of 1.4 or lower. Should you later decide to upgrade your peer to a v2.x image and update your channel application capability level to 2.0, you may need to update your existing smart contract. However, after you upgrade your peer image to v2.x and channel application capability v2.x, there is no longer a way to update the original smart contract. Instead, when an update is required, you need to repackage the smart contract in the new .tar.gz or .tgz format using v2 of the VS Code extension and then propose the definition to the channel using the new smart contract lifecycle process.

Review the following considerations:

Node

If your smart contract was written in Node, then you might need to update it. By default, a Fabric v1.4 peer will create a Node v8 runtime, and a Fabric v2.x peer creates a Node v12 runtime. In order for a smart contract to work with Node v12 runtime, the fabric-contract-api and fabric-shim node modules must be at v1.4.5 or greater. If you are using a smart contract that was originally written to work with Fabric 1.4, update the Node modules by running the following command before deploying the smart contract on a Fabric v2.x peer. See Support and compatibility for fabric-chaincode-node for more information.

npm install --save fabric-contract-api@latest-1.4 fabric-shim@latest-1.4

Go

Because Fabric v2.x peers do not have a "shim" (the external dependencies that allowed smart contracts to run on earlier versions of Fabric), you need to vendor the shim and then repackage any smart contracts written in Golang (Go) that use the Go SDK. "Vendoring the shim" effectively means that you are copying the dependencies into your project. Without this vendoring and repackaging, the Go smart contract cannot run on a peer using a Fabric 2.x image. If you are using the IBM Developer Tools to develop and package your smart contract, the tooling performs the vendoring for you. This process is not required for smart contracts that are written in Java or Node.js, nor for Go smart contracts that use the Go contract-api.

Java
The build.gradle file for the smart contract must be updated:

1. If the smart contract uses the shadowjar 2.x plugin, then it should be updated to version 5 by using the following code:

   plugins {
       id 'com.github.johnrengelman.shadow' version '5.1.0'
       id 'java'
   }
   

2. The repositories section of the file must contain the maven URL for jitpack, for example:

       repositories {
       ...
       maven {
           url 'https://jitpack.io'
       }
   }
   

Init functions

If the smart contract was written using the low-level APIs provided by the Fabric Chaincode Shim API, your smart contract needs to contain an Init function that is used to initialize the chaincode. This function is required by the smart contract interface, but does not necessarily need to be invoked by your applications. Because you cannot use the console to deploy a smart contract that contains an Init function, you need to move that initialization logic into the smart contract itself and call it separately. For example, the smart contract can use a reserved key to check whether the smart contract has already been initialized or not. If not, then call the initialization logic, otherwise proceed as usual. If your smart contract needs to include the Init function, the only way to deploy it is by using the Fabric peer lifecycle chaincode install command or the IBM Blockchain Platform collection for Ansible. You can also refer to the Fabric documentation for more details on how to use an Init function with the Fabric chaincode lifecycle.

Repackage smart contract

Attention! The IBM Blockchain Platform Extension for VS Code (VS Code extension) referenced throughout the documentation is an open-source project which is no longer active, and therefore not officially supported by IBM. Refer to the alternatives to the VS Code extension.

After you have updated your smart contract, use v2 of the VS Code extension to repackage your smart contract.

For a look at how the new lifecycle is administered in the console, check out Deploy a smart contract using Fabric v2.x. For a look at the possibilities the new lifecycle opens up, check out Writing powerful smart contracts.

Step four: Update capabilities

Once your nodes, SDKs, and smart contracts have been upgraded to use the latest Fabric version, you can update your channel configuration to use the latest capabilities. Note that the Fabric version of your nodes must be at least at the corresponding capability level of the channel the node is joined to.

For more information about capabilities and how to update a channel configuration to enable them, check out Capabilities.