1. Administering Oracle Blockchain Platform
  2. Manage Oracle Blockchain Platform

6 Manage Oracle Blockchain Platform

Once you've provisioned your instance, you can manage it in Blockchain Platform Manager.

Topics

View Instance Details

Clicking on your instance name in Blockchain Platform Manager opens the Instances tab displaying details about the instance.

The Instance Details page lists information such as the location of the logs and ledger, as well as the health of the instance. You can also see all the VMs and their status.

The Patching page lists all the patches that have been applied to the instance, as well as any available patches that haven't been applied.

You can manage the instance from the Actions menu, or launch the Oracle Blockchain Platform Service Console to manage your blockchain network.

Open the Configuration tab to access the LDAP and platform configuration tabs. You can update your LDAP or platform configuration if needed. You may want to disable the default user (obpadmin) once you've created your user in LDAP and successfully logged in with that user ID.

View Instance Activity

The Activity pages shows the status of operations that have been performed on your instances.

To see the activity of an instance, select your instance name and on the Instances page click Activity.

This tab lists any operations that have been performed on your instance such as starting, stopping, and updating, as well as whether or not it was successful, the time of the operation, and the user ID who initiated the operation.

You can see and filter the activity of all instances managed by Blockchain Platform Manager on the Activities page. The Activities page can be used to see the history of operations performed on any instances, including deleted instances. These activities can be filtered by different search criteria such as instance name, operation types, and date range.

Start or Stop an Instance

You can start or stop an instance in the Blockchain Platform Manager.

To start or stop an instance:
  1. In Blockchain Platform Manager, find your instance and select the menu beside it.
  2. Select Start or Stop. You'll be prompted to confirm your selection.

Delete an Instance

You can delete your instance in Blockchain Platform Manager.

To delete your instance:
  1. Open Blockchain Platform Manager and find your instance.
  2. From the menu beside your instance, select Terminate.
  3. You'll be prompted to confirm you action. Click Confirm.

Scale an Instance In or Out

You can scale an instance in or out in Blockchain Platform Manager.

Scale Out

You can scale out your instance by creating new VMs, replicas, or peers:

  1. In Blockchain Platform Manager open the menu beside your instance name and click Scale Out.
  2. You can scale out using any of these methods:
    • New VMs: adds a new VM to the cluster with the specified role of platform host, chaincode host, or ZooKeeper/Kafka host.
    • New Replicas: adds additional nodes; REST proxy or CA.
    • New Peers: adds one additional peer at a time.

Scale In

You can scale in your instance by deleting peers.

Before scaling in an instance, you should transfer all this peer's responsibilities to other running peers, and then remove all the responsibilities this peer has.
  • Check all other peers' gossip bootstrap address lists, remove the peer address, and add another running peer's address if needed. After peer configuration change, restart the peer.
  • Check all channels' anchor peer lists, remove the peer from the anchor peer lists, and add another running peer to the anchor peer list if needed.
  • If a channel or chaincode is only joined or instantiated in this peer, you should consider using another running peer to join the same channel and instantiate the same chaincode.
  1. In Blockchain Platform Manager open the menu beside your instance name and click Scale In.
  2. Enter the hostname or IP address of the peer you want to delete. To delete more than one peer, click Add Peer and enter the information for the additional peer.

Patch an Instance

You can patch Blockchain Platform Manager and your instance from within Blockchain Platform Manager.

Register a Patch

  1. Download any desired patches from support.oracle.com.
  2. Open the Patches tab.
  3. Click Register Patch and select the patch you've downloaded.

Patching Blockchain Platform Manager

When a Blockchain Platform Manager patch is available, you must apply it before patching your instance. Otherwise when you are trying to do the data plane patching a warning message will be shown to remind you patch the control plane first.

  1. When a Blockchain Platform Manager patch is available, an Upgrade button will be shown in the About dialog which you can open from the User menu in the top-right corner.
  2. The Blockchain Platform Manager patching process will reboot Blockchain Platform Manager automatically. After the reboot, you need to clean up cached images and files in the browser, then log in to the Blockchain Platform Manager again.

Any new instances created after the patch will be at the upgraded level. Any existing instances must be patched as described in Patching an Instance.

Patching an Instance

You must have patched Blockchain Platform Manager before you patch you instance.

A patch package includes:

  • A metadata file
  • One or more scripts to be run during patching
  • Docker images for different components

Blockchain Platform Manager extracts the patch package, pushes the component docker images to the docker registry, and stores the metadata file and scripts in local database.

The patch package is a rolling patch; a newer patch is always a superset of an older patch within the same release.

  1. Open the Patches page. Select the registered patch you want to apply and click Apply. Select all the instances you want to apply the patch to, click Next and then Submit.
  2. Patching is an asynchronous operation. In the instance's Activity pane, click Refresh to check the operation's status periodically and wait until the status changes to Successful.

To Roll Back a Patch

In Blockchain Platform Manager:
  1. On the Instances tab, select your instance to open the Instance Details page and select the Patches tab.
  2. Select the patch to be rolled back, and click Rollback.

Post-Patching Steps

After you patch your instance, the Blockchain Platform Manager UI may not be updated. Clear your browser cache and reload the Blockchain Platform Manager to see the updated pages.

For information on how to configure logging for a patched instance, see Migrated Instance Logs

Back Up an Instance

You can use a rolling backup procedure to back up instances of Oracle Blockchain Platform Enterprise Edition.

The following steps describe how to back up an instance by using Oracle VM VirtualBox or a similar virtualization tool that can export and import the contents of VMs. Typically, you back up and restore an instance during a maintenance window, when the load on the system is low. Do not run any administrative actions in the service console until the backup procedure is complete.

The following procedure assumes that you will use Oracle VM VirtualBox to import the VM image to the same host system. If you plan to restore the VM image to a different host system, additional steps might be needed, which are not covered in this topic.

For a typical high availability scenario, to back up instances in a live environment without affecting normal operations, your configuration must meet the following requirements:
  • The instance uses the Enterprise configuration, and includes at least three Oracle Blockchain Platform host VMs, three Kakfa host VMs and three chaincode host VMs. Separate from these hosts, Blockchain Platform Manager must be installed on a separate host VM.
  • The instance has a sufficient number of peers and orderer service instances, based on the sizing and usage. Typically, you need at least two peers and one orderer per platform host.
  • All of the platform hosts, Kafka hosts, and chaincode hosts are located on different computers, and at least one host of each type is in a different region.
  • The instance uses an external load balancer which is configured to route requests to the active service instances when other service instances are stopped. The external load balancer must be running on a separate VM and must be available during the entire backup process. If an external load balancer is not available, then there will be downtime when the first platform host is stopped for backup.
  • The applications used by the instance are configured to retry failed transactions. If a platform host or chaincode host is not available, intermittent failures can occur when running transactions using the REST proxy or SDK. If a transaction fails, the application must attempt the transaction again on a different platform host or chaincode host until the transaction succeeds.
  • The authentication server is external to the instance and configured to be highly available. The authentication server is not backed up as part of this procedure.
  1. Back up the chaincode hosts, one at a time.
    1. Stop one chaincode host, and ensure that all other chaincode hosts are still running.
    2. Export the VM contents of the stopped host. In Oracle VM VirtualBox, select File and then select Export Appliance. For Format, select Open Virtualization Format 1.0. If you plan to restore the backup to the same system, specify the MAC Address Policy to retain network adapter MAC addresses.
    3. Start the chaincode host.
    4. Repeat the previous steps for all other chaincode hosts.
  2. Back up the Kafka hosts, one at a time.
    1. Stop one Kafka host, and ensure that all other Kafka hosts are still running.
    2. Export the VM contents of the stopped host. In Oracle VM VirtualBox, select File and then select Export Appliance. For Format, select Open Virtualization Format 1.0. If you plan to restore the backup to the same system, specify the MAC Address Policy to retain network adapter MAC addresses.
    3. Start the Kafka host.
    4. Use the docker ps command to verify that Kafka and Zookeeper containers are running normally in the VM.
    5. Repeat the previous steps for all other Kafka hosts.
  3. On the Nodes tab of the service console, click the More Actions icon to determine which peer and orderer nodes are running on each platform host. Record this information to use in the following steps to back up the platform hosts, one at a time.
    1. Use the service console or REST API to stop the peer and orderer nodes on the first platform host.
    2. Stop the platform host, and ensure that all other platform hosts are still running.
    3. Export the VM contents of the stopped host. In Oracle VM VirtualBox, select File and then select Export Appliance. For Format, select Open Virtualization Format 1.0. If you plan to restore the backup to the same system, specify the MAC Address Policy to retain network adapter MAC addresses.
    4. Start the platform host.
    5. Start the peer and orderer nodes that were running on the platform host.
    6. Verify that the peer and orderer nodes are running normally.
    7. Repeat the previous steps for all other platform hosts.
  4. Back up the Blockchain Platform Manager.
    1. Stop the Blockchain Platform Manager host.
    2. Export the VM contents of the stopped host. In Oracle VM VirtualBox, select File and then select Export Appliance.
    3. Start the Blockchain Platform Manager host.
You might see the following types of intermittent failures returned by the REST proxy when you stop a host VM during the backup procedure.
  • When a chaincode host is stopped, an error similar to the following text might be returned.
    {
"returnCode": "Failure",
"error": "Transaction processing for endorser [<Host FQDN>:15036]: Chaincode status Code: (500) UNKNOWN. Description: failed to execute transaction f04fa964c4eae9387d2f97887a3558118412b0c6b76a33d75f17572c37c20918: error sending: timeout expired while executing transaction",
"result": null
}
  • When a chaincode host is restarting, an error similar to the following text might be returned.
    {
"returnCode": "Failure",
"error": "Transaction processing for endorser [<Host FQDN>:15039]: Chaincode status Code: (500) UNKNOWN. Description: failed to execute transaction 7dbb9966b40ecb07b811dc2e6a23cea899e791f4eeb80d5e1b15daa10350aa6a: [channel mychan2] could not launch chaincode obcs-example02:v0: error starting container: error starting container: Post https://<HOST FQDN>:2376/containers/create?name=dev-6aae07b4-779c-4752-bcb9-4df010503168-peer3-obcs-example02-v0: dial tcp <IP Address>:2376: connect: no route to host",
"result": null
}
  • Additionally, transient timeout errors can occur, similar to the two following examples.
    {
"returnCode": "Failure",
"error": "Transaction processing for endorser [<External LBR FQDN>:15041]: Chaincode status Code: (500) UNKNOWN. Description: failed to execute transaction 7fb7f989a88ac3b068052ccd3f9acce555c6319d0cfe975fcfdd6a84b32fe421: error sending: timeout expired while executing transaction",
"result": null
}

    {
"returnCode": "Failure",
"error": "Failed to get endorsing peers: Discovery status Code: (11) UNKNOWN. Description: error getting endorsers: no endorsement combination can be satisfied",
"result": null
}

Restore an Instance

After you complete the backup procedure, you can restore an instance that is not working correctly or is unusable.

The following steps describe how to restore an instance by using Oracle VM VirtualBox or a similar virtualization tool that can export and import the contents of VMs. When you restore an instance from backup, the instance must be completely stopped.
  1. Use Oracle VM VirtualBox to stop all of the platform hosts, chaincode hosts, and Kafka hosts that are used by the instance.
  2. Rename all of the VMs to ensure that there is no name collision when you import the VM contents that you exported during the backup process.
    For example, add the suffix _backup to all of the VM names.
  3. One at a time, import (but do not start) each of the VM images that you created during the backup procedure for all of the platform hosts, chaincode hosts, and Kafka hosts.
  4. Start each platform host and verify that all the platform hosts are running normally. Use the ping command with the fully-qualified domain name of each host to very that all platform hosts are accessible to each other on the network.
    By default, the first platform host is the Docker swarm leader. Start the first platform host before any other platform hosts.
  5. Start each chaincode host and verify that all the chaincode hosts are running normally. Use the ping command with the fully-qualified domain name of each host to very that all chaincode hosts and all platform hosts are accessible to each other on the network.
  6. Start each Kakfa host and verify that all the Kafka hosts are running normally. Use the ping command with the fully-qualified domain name of each host to very that all Kafka hosts are accessible to each other on the network.
  7. From one of the platform hosts, verify that all hosts are active and accessible by running the docker node ls command. All hosts in the network must show Ready status and Active availability. You might need to wait a few minutes for network configuration to complete for all hosts to be active and ready.
  8. Log in to the Oracle Blockchain Platform console for the instance. On the Nodes tab, start all of the orderer nodes and then all the peer nodes. Verify that all the orderer nodes and peer nodes are running normally. If there are any failures, check the logs for the details. Typically, all the peer and orderer nodes start normally and the instance is then available to use.
  9. If you need to restore the Blockchain Platform Manager host, stop the current host and rename it, then import the image backup and restart the host.