Refer to Code Upgrade 1.x from 2.0 Guidelines for specific guidelines on how to upgrade a 1.x CCF service to 2.0.
This page describes how operators/members can upgrade a live CCF service to a new version with minimal downtime.
Reasons for running the code upgrade procedure include:
Upgrading nodes to a new version of CCF.
If more than a majority of nodes have failed, the disaster recovery procedure should be run by operators instead (see Disaster Recovery).
CCF guarantees specific live compatibility across different LTS versions. See Operations compatibility for more details.
Let’s assume that the to-be-upgraded service is made of 3 nodes (tolerates up to one fault, i.e.
f = 1), with
Node 1as the primary node (the code upgrade procedure can be run from any number of nodes):
First, operators/members should register the new code version corresponding to the new enclave measurement using the
add_node_codeproposal action (see Updating Code Version).
The set of new nodes running the enclave registered in the previous step should be added to the service (see Adding a New Node to the Network) and trusted by members (see Trusting a New Node). Typically, the same number of nodes than were originally present should be added to the service. In this example, the service is now made of 6 nodes (
f = 2).
The original nodes (
Node 2) can then safely be retired.
Node 0is retired, 5 nodes remaining,
f = 2:
Node 1(primary) is retired, 4 nodes remaining,
f = 1.
Node 4becomes primary after election phase (during which service cannot temporarily process requests that mutate the state of the key-value store):
It is possible for another old node (e.g.
Node 2) to become primary when the old primary node is retired. However, eventually, the primary-ship of the service will be transferred to one of the new nodes (e.g.
Node 2is retired, 3 nodes remaining,
f = 1:
Once all old nodes
2have been retired, and they are listed under
GET /node/network/removable_nodes, operators can safely stop them and delete them from the state (
Members should be use the
set_constitutionproposal action to update the constitution scripts.
Finally, once the code upgrade process has been successful, the old code version (i.e. the code version run by nodes 0, 1 and 2) can be removed using the
GET /node/versionendpoint can be used by operators to check which version of CCF a specific node is running.
A code upgrade procedure provides very little service downtime compared to a disaster recovery. The service is only unavailable to process write transactions while the primary-ship changes (typically a few seconds) but can still process read-only transactions throughout the whole procedure. Note that this is true during any primary-ship change, and not just during the code upgrade procedure.