This section describes the upgrade procedure for IPFS Cluster. There are several considerations:
X.X.X, including the patch number)
The following upgrade procedure provides the fastest and most straightforward upgrade path. It plays nicely with any deployment automation tools or with docker.
For this method to work it is required that:
leave_on_shutdownis set to
wait_for_leader_timeoutis sufficiently high to account for the restart of all peers (default should be ok in most cases)
ipfs-cluster-ctlbinaries (or containers)
ipfs-cluster-service daemon --upgradesimultaneously.
This will perform any state format migrations when necessary. Since all the peers start at once, using the new version of
ipfs-cluster-service and with an up to date state, the cluster will be ready to work right away.
If you are using Docker, replacing your containers with the new image should be enough (it runs
ipfs-cluster-service daemon --upgrade by default).
Another way to perform an update is to sequentially remove the peers of the cluster, upgrade them, and the bootstrap them again.
ipfs-cluster-ctl peer rm <peerID>for each cluster peer, except the last (a single-peer cluster will not remove its only peer).
ipfs-cluster-service state upgradeand restart the peer (or simply restart it with
ipfs-cluster-service daemon --upgrade)
ipfs-cluster-service daemon --bootstrap <multiaddress>.
The most important thing when performing an upgrade is to keep the cluster state (which stores the pinset) safe.
If the peers are removed from cluster, the state is automatically cleaned, but a backup copy is stored (see data persistence and backups). You can always recover a backed up state by renaming the backup folder to the original name (
raft). Then, you can export the state and import it on a different peer if needed (
state export/import), making sure that it is running the same version as the peer from which it was exported.
Finally, as long as you have a valid state, you can upgrade the format with
ipfs-cluster-service state upgrade after installing the new IPFS Cluster version. So, a full disaster recovery procedure would be as follows:
raftor as a backup copy of it
ipfs-cluster-service state export
ipfs-cluster-service state importto import the state copy from step 2
ipfs-cluster-service state upgradeto upgrade the imported state