4 Upgrade to Version 21

Before you begin the upgrade process, take a snapshot of the current state of the virtual machine (VM). Rollback from version 21.1.2 is not supported.

Topics

• Enable Transport Layer Security
• Patch to v19.3.6
• Check Available Disk Space
• Upgrade Instances to Version 21
• Update External Load Balancer Port Mapping
• Configure Raft Consensus Protocol

Enable Transport Layer Security

The built-in LDAP server that is bundled with Oracle Blockchain Platform Enterprise Edition Version 21 supports only Transport Layer Security (TLS) connections on port 636.

Note:

If you currently use the built-in LDAP server with TLS disabled, you must complete the following steps to enable TLS before attempting to upgrade to Version 21.

1. Open the Configuration tab.
2. Under Authentication Servers, select Default and set TLS Enabled to True.
3. Click Test Configuration to ensure that the settings work.
4. Click Save, then click Set Active.
5. Open the Instances tab.
6. For each instance that uses the built-in LDAP server, click the instance name to open the Instance Details page. From the Actions menu, use the Update option, select Update Auth Server Configuration, and then complete the update.

Patch to v19.3.6

Patch the instance to version 19.3.6.

You must complete the intermediate step of patching Blockchain Platform Manager and all founder and participant instances to version 19.3.6 before you upgrade to Version 21. For more information, see Patch an Instance to v19.3.5 or Later.

Check Available Disk Space

Each instance requires approximately 35 GB available disk space to upgrade to Version 21.1.2.

1. In the /dev/mapper/vg00-var directory, run the following command to check for available disk space:

   df -h

   You need approximately 35 GB available disk space to upgrade to Version 21.

2. To increase available disk space, complete the following steps. Login as root.
   sudo su
3. Run vgdisplay to determine the free space that can be used for the /dev/mapper/vg00-var directory.
   For example, the following output indicates that approximated 24 GB can be used:

   Alloc PE / Size 18241 / 71.25 GiB Free PE / Size 6504 / <25.41 GiB

   In this case, the following commands add 24 GB to the /dev/mapper/vg00-var directory.

   lvextend /dev/mapper/vg00-var -L +24G
   resize2fs /dev/mapper/vg00-var
   resize2fs /dev/mapper/vg00-home

4. After you add space to the /dev/mapper/vg00-var director, run the df -h command again to check that there is at least approximately 35 GB space.

Upgrade Instances to Version 21

You upgrade from Version 19 to Version 21 by patching instances. However, you must run also run a script after registering the patch and before applying the patch.

All custom enrollments are migrated when you upgrade to version 21.1.2, but the user associations with the enrollments are not migrated. After you upgrade an instance to version 21.1.2, you must add the user associations to custom enrollments from the console.

1. Register the version 21.1.2 patch. For more information, see Patch an Instance to v19.3.4. Complete only the steps under Register a Patch.
2. In sudo mode, navigate to the /u01/blockchain/cp/config/scripts-21.1.2 directory and run the following command: sh patchUpdates.sh -VMType bpm.
   This step can take up to approximately twenty minutes to complete.
3. Patch Blockchain Platform Manager and the instance. For more information, see Patch an Instance to v19.3.4. Complete the steps under Patching Blockchain Platform Manager and Patching an Instance.

To re-associate users with custom enrollments, on the Nodes tab of the console find the restproxy node. From the Action menu, select View or manage enrollments. On the Enrollment Management page, select the enrollment under Enrollment ID and then add users to the enrollment by expanding Associate New Users and entering the user IDs. After you add all of the users, click Associate.

Update External Load Balancer Port Mapping

All instances that use an external load balancer must be reconfigured after upgrading to Version 21.

In Version 21, the CA and REST proxy share the same port as the console, so the port mappings for the CA and REST proxy as well as for Prometheus are no longer needed. Also, the orderer Raft port is the same as the orderer query port in Version 19, but the Raft port is not enabled for TLS. If you use an external load balancer, you must update the configuration to account for these changes.

1. Remove the CA, REST proxy, and Prometheus sections from the external load balancer configuration in the nginx.conf file.
   For example, remove the following sections from the nginx.conf file.

       upstream server_server1_restproxy_47201 {
           server server1.example.com:10001;
       }
       server {
           listen *:47201 ssl;
           proxy_pass server_server1_restproxy_47201;
           ssl_certificate     /etc/nginx/certs/cert.pem;
           ssl_certificate_key /etc/nginx/certs/key.pem;
       }
       upstream server_server1_ca_47202 {
           server server1.example.com:10002;
       }
       server {
           listen *:47202 ssl;
           proxy_pass server_server1_ca_47202;
           ssl_certificate     /etc/nginx/certs/cert.pem;
           ssl_certificate_key /etc/nginx/certs/key.pem;
       }
       upstream server_server1_prometheus_47203 {
           server server1.example.com:10003;
       }
       server {
           listen *:47203 ssl;
           proxy_pass server_server1_prometheus_47203;
           ssl_certificate     /etc/nginx/certs/cert.pem;
           ssl_certificate_key /etc/nginx/certs/key.pem;
       }

2. Ensure that the second (Raft) port on every orderer in the network does not use SSL.
   In the following example, the second port no longer uses SSL.

   upstream server_server1_orderer0_47204 {
           server server1.example.com:10004;
       }
       server {
           listen *:47204 ssl;
           proxy_pass server_server1_orderer0_47204;
           ssl_certificate     /etc/nginx/certs/cert.pem;
           ssl_certificate_key /etc/nginx/certs/key.pem;
       }
       upstream server_server1_orderer0_47205 {
           server server1.example.com:10005;
       }
       server {
           listen *:47205;
           proxy_pass server_server1_orderer0_47205;
           ssl_certificate     /etc/nginx/certs/cert.pem;
           ssl_certificate_key /etc/nginx/certs/key.pem;
       }

3. Restart nginx.

Configure Raft Consensus Protocol

Version 21 of the product uses Raft-based ordering instead of Kafka-based ordering. You change the consensus type from Kafka to Raft by collecting channel and instance information and running scripts.

Complete the following steps only after all founder and participant instances are upgraded to version 21.1.2.

1. In the Blockchain Platform Manager virtual machine (VM) and in all instance VMs, navigate to the /u01/blockchain/cp/config/scripts-21.1.2 directory, then from the root account run the config-obplog.sh script to redirect logs from /var/log/messages to /u01/obp-logs/.
2. In all instance VMs, complete the following steps.
   1. Use ssh to log in and then run the following command to open a command prompt in the Docker container: docker exec -it bcscm bash.
   2. Run the following command to create the /cm/instances directory: mkdir /cm/instances.
   3. On the founder instance, in the /cm/instances directory, create a JSON file for the channel names and names of participant organizations.
      For example, if the founder instance has channels named default and channel1 and participant organizations named partner1 and partner2, create a JSON file similar to the following text. The testchainid channel is the default system channel and must be included in the file. If there are no participant organizations, include an empty participants array. If there are participant organizations that are no longer active or have left the network, move any channels that were created by those organizations to the discards array. Also move any channels where less than 50 percent of the organizations are active to the discards array.

      {
      "channels": [
      "testchainid",
      "default",
      "channel1"
      ],"discards": [
      ],
      "participants": [
      "partner1",
      "partner2"
      ]
      }

   4. On each participant instance, generate an msp directory archive by running the getParticipantAdminCerts.sh script in the /u01/blockchain/cp/config/scripts-21.1.2 directory, with the participant instance name as a parameter.
      For example, getParticipantAdminCerts.sh participant_instance_name.
      The script creates the participant_instance_name.msp.tar.gz file.
   5. On each participant instance, run the following command to extract the msp directory archive: tar -xvf instance_name.msp.tar.gz.
   6. Copy the msp directory from each participant organization to the /cm/instances directory on the founder instance. Specify the name of the participant organization as the subdirectory name.
      For example, if the name of the participant organization is partner1, copy the msp directory from partner one to /cm/instances/partner1.
   7. On the founder instance, navigate to the /cm/script directory, and then run the following command to change the consensus type from Kafka to Raft. If the name of the JSON file that you created previously is channels.json, run the following command: ./kafka2raft.sh -c /cm/instances/channels.json -a /cm/instances
      After the script completes, the instance is active and no Kafka containers are running.
   8. On all participant instances, navigate to the /cm/script directory, and then run the following command to change the consensus type from Kafka to Raft: ./kafka2raft.sh
3. On all participant instances, import the ordering service settings from the founder instance.
   1. In the founder console, on the Network tab find the founder organization. Select the Action menu for the founder organization and then select Export Orderer Settings.
      This generates a JSON file with the settings and saves the file.
   2. In each participant console, open the Network tab. Click Orderer Settings and then Import. A window opens prompting you for the location of the JSON file provided by the founder. Select to upload the file and click Add.
4. On each data plane VM, navigate to the /u01/blockchain/cp/config/scripts-21.1.2, and in sudo mode run the following command: sh patchUpdates.sh -VMType instance.
5. Open the Instances tab in Blockchain Platform Manager and then, for each instance that you upgraded, click the instance name to open the Instance Details page.

By default, Developer instances in version 19 included only two orderers. After you complete the upgrade to version 21.1.2 and the change to Raft consensus protocol, add another orderer so that at least three are available. For more information, see Scale an Instance In or Out.