3 Manage the Life Cycle of an Instance

You can use the Instances page of the Oracle Cloud Infrastructure Console to perform routine maintenance or troubleshooting for your Oracle Blockchain Platform instance.

Start or Stop an Instance

You can start or stop an instance using the Oracle Cloud Infrastructure console or the REST APIs.

To start or stop an instance in the console:
  1. In the Oracle Cloud Infrastructure console, under Developer Services, select Blockchain Platform.
  2. Select the correct compartment, and click the instance you want to start or stop.
  3. Select Start or Stop. You'll be prompted to confirm your selection.
To start or stop an instance using the REST APIs, you can use the following operations. Refer to the REST API Reference for information about how to use these operations:
  • /20191010/blockchainPlatforms/{blockchainPlatformId}/actions/start
  • /20191010/blockchainPlatforms/{blockchainPlatformId}/actions/stop

Upgrade an Instance

When a new release is available, you can upgrade an instance by using the Oracle Cloud Infrastructure console or the REST APIs.

When a new release is available, you will receive a notification from the Oracle Cloud Infrastructure Notifications service. To upgrade your instance before the specified deadline, complete the following steps. If you don't upgrade the instance by the deadline, the instance is upgraded automatically.
  1. In the Oracle Cloud Infrastructure console, under Developer Services, select Blockchain Platform.
  2. Select the correct compartment, and click the instance that you want to upgrade.
    A message is displayed that indicates a new version is available.
  3. Click Upgrade Platform Instance, and then click Upgrade to confirm.

    Note:

    Oracle Blockchain Platform restarts as part of the upgrade process. The system remains available for most of the upgrade process, but is not available while it restarts, which can typically take up to ten minutes.
    The State Message changes to Upgrading and an entry of the Upgrade Blockchain Platform type is displayed in the Work Requests table.

Upgrade the Platform Version of an Instance

When a new platform version is available, you can upgrade an instance by using the Oracle Cloud Infrastructure console.

The platform version is the version of Hyperledger Fabric that Oracle Blockchain Platform is based on. When a new version is available, you will receive a notification from the Oracle Cloud Infrastructure Notifications service. For example, you will receive a notification that you can upgrade an instance that is based on Hyperledger Fabric v1.4.7 to Hyperledger Fabric v2.2.4. To learn more about platform versions, see What's a Platform Version?.
  • The platform upgrade function to Hyperledger Fabric v2.2.4 is available only for founder instances with no participant instances in the same network. If your Oracle Blockchain Platform network contains multiple instances (founder and participants), Oracle will assist you with the upgrade. For more information, see Request a Platform Upgrade for Multiple Instances.
  • Upgrading to Hyperledger Fabric v2.2.4 means that you will use a new chaincode life cycle and a new model that separates chaincode packages from chaincode definitions. To learn more about the new features, see Deploy and Manage Chaincodes on Hyperledger Fabric v2.2.4. When you upgrade the platform version, you might need to make changes to your existing applications and REST API calls so that they work with the new version of Hyperledger Fabric. To learn more about the impact of a new version of Hyperledger Fabric on existing applications, see Updating Applications for Hyperledger Fabric v2.2.4.
  • Because client SDK versions have to be upgraded to work with Hyperledger Fabric v2.2.4, for applications that use client SDKs typically you first upgrade and verify them in a test environment before upgrading your production environment.
  • When you upgrade an instance from Hyperledger Fabric v1.4.7 to Hyperledger Fabric v2.2.4, the ordering service settings are not updated. In other words, an upgraded instance uses the existing ordering service settings of the Hyperledger Fabric v1.4.7 instance, not the default settings for a new Hyperledger Fabric v2.2.4 instance. For more information about the ordering service, see Manage Ordering Service.
  • The typical downtime for a platform upgrade is 60 minutes for a single founder instance.
  • Once the upgrade starts, all traffic to the instance is rejected until the upgrade completes. In other words, no administrative operations or transactions can be processed during the platform upgrade process.

To upgrade the platform version of an instance, complete the following steps.

  1. Review the impact to existing client applications and REST API calls and plan any required updates. For more information, see Updating Applications for Hyperledger Fabric v2.2.4.
  2. In the Oracle Cloud Infrastructure console, under Developer Services, select Blockchain Platform.
  3. Select the correct compartment, and click the instance that you want to upgrade.
    A message is displayed that indicates a new platform version is available.
  4. Click Upgrade Platform Instance, and then click Upgrade to confirm.

    Note:

    Oracle Blockchain Platform will not be available during the upgrade process, which typically takes 60 minutes or less for a single instance.
    The State Message changes to Upgrading and an entry of the Upgrade Blockchain Platform type is displayed in the Work Requests table.
When the upgrade is complete, the state of the Upgrade Blockchain Platform work request changes to Succeeded and the Platform Version displays the new version of Hyperledger Fabric. In the Oracle Blockchain Platform console, all of the previously instantiated Hyperledger Fabric v1.4.7 chaincodes are displayed in the Deployed Chaincodes list for each specific channel page under the Channels tab, with the Sequence, Package ID, Approved, and Committed settings all shown as N/A. Where the Chaincode tab for the Hyperledger Fabric v1.4.7 platform displayed the fields Chaincode ID, Versions, Chaincode Path, Installed on Peers, and Instantiated on Channels, the Chaincodes tab for the Hyperledger Fabric v2.2.4 platform displays the fields Package ID, Installed on Peers, and Deployed on Channels. Existing Hyperledger Fabric v1.4.7 chaincodes are not listed as installed on the Chaincodes tab. When chaincode packages are installed again, they will be listed on the Chaincodes tab. After the upgrade, you must use Hyperledger Fabric v2.2.4 life cycle operations to deploy new or upgrade existing chaincodes.
After the instance is upgraded, complete the following steps:

Request a Platform Upgrade for Multiple Instances

If your Oracle Blockchain Platform network contains multiple instances (founder and participants), Oracle will assist you with the platform upgrade.

The upgrade from Hyperledger Fabric v1.4.7 to Hyperledger Fabric v2.2.4 must be coordinated across all instances in your network. The Oracle DevOps team uses internal tools and processes to complete the upgrade. The downtime for the platform upgrade process is a function of the number of instances, and is typically in the range of 4 to 10 hours.

The platform upgrade includes the following high-level steps:

  • You review the impact to existing chaincodes, client applications, and REST API calls and make any required updates. For more information, see Updating Applications for Hyperledger Fabric v2.2.4. Due to the potential impact to existing applications, typically you will schedule with the Oracle DevOps team to upgrade your test environment or stage environment first before upgrading your production environment.
  • You submit a service request to Oracle to upgrade a specified set of instances that belongs to one or more Oracle Blockchain Platform networks, and provide a contact to coordinate the upgrade. To request an upgrade, open a service request (SR) in My Oracle Support. To learn more about Service Requests, see the documentation that is available at My Oracle Support. Include the following information in the Service Request:
    • Oracle Cloud Infrastructure region
    • Tenancy name
    • Oracle Blockchain Platform instance names
  • The Oracle DevOps team coordinates the upgrade schedule with you.
    • All instances in an Oracle Blockchain Platform network must be upgraded in the same time period.
    • Once the upgrade starts, all traffic to the instances is rejected until the upgrade completes. In other words, no administrative operations or transactions can be processed during the platform upgrade process.
  • The Oracle DevOps team runs the platform upgrade process and then notifies the specified customer contact when the upgrade is complete.
  • After instances are upgraded, update your client application if needed and verify that your client application works on the upgraded instances. For more information, see Updating Applications for Hyperledger Fabric v2.2.4.

Delete an Oracle Blockchain Platform Instance

When you no longer require an Oracle Blockchain Platform instance, you can delete it. Your account is no longer charged for the instance.

Only a blockchain administrator can delete a service instance. See Assigning Roles for the Oracle Blockchain Platform Network and REST APIs.

To delete an Oracle Blockchain Platform instance:
  1. In the Oracle Cloud Infrastructure console, select Developer Services, select Blockchain Platform.
  2. Select the correct compartment, and click the instance you want to delete.
  3. From the More Actions dropdown, select Terminate.
  4. You will be asked to confirm your selection. Note that all information in the ledger will be lost when you terminate the instance.

Scale Your Instance

You can scale your overall instance OCPU capacity or the components of any instance.

Scaling the OCPU Capacity of an Enterprise Instance

If you've selected an Enterprise edition when provisioning your instance, you can scale its OCPU capacity up or down. When you scale OCPU capacity, the platform shape changes to Custom in the Instance Details view. The total OCPU capacity represents the total number of OCPUs that are equally allocated among all the VMs in the Oracle Blockchain Platform cluster.

To change your OCPU capacity:
  1. In the Oracle Cloud Infrastructure console, under Developer Services, select Blockchain Platform.
  2. Select the correct compartment, and click the Enterprise instance that you want to modify.
  3. In the Instance Details view, click Scale, and then from the Select Scale Object drop-down list select Platform.
  4. You are prompted to select the number of OCPUs that you want provisioned for this instance.

    Note that the resizing process will take several minutes and will result in downtime of your Oracle Blockchain Platform instance.

Your instance is now resized to its new OCPU capacity and is listed as a customized edition.

Scaling Components of Your Instance

You can scale components of your instance by selecting it in the Oracle Cloud Infrastructure console and clicking Scale.

Peers
  • You can change the OCPUs for the peer nodes. The total value of the OCPUs must not exceed the size of the instance edition that you selected when scaling your instance. After you select the OCPUs for a peer, you can decrease the OCPU allocation if required.
  • You can add a new peer by clicking Add Row and selecting the alias, OCPUs, role, and availability domain or fault domain for that peer.

Note:

When scaling peers, the OCPUs field is a logical representation of processing power, which is used to determine whether a newly scaled peer will be placed on an existing VM or a new VM. It does not map to the actual number of OCPU cores enabled on the virtual machine (VM).

You can see the availability domains or fault domains for the existing peers on the Scale Blockchain Platform window. Each Oracle Blockchain Platform instance is deployed across three availability domains or fault domains.

You can use the following REST API call to get more information about the logical OCPU consumption for each VM: Get Blockchain Platform Information.

The peers array in the BlockchainPlatformComponentDetails object shows information for each peer, including the host where the peer is located and the ocpuAllocationNumber, which indicates the number of OCPUs allocated to the peer.

The hostOcpuUtilizationInfo array shows the ocpuCapacityNumber and ocpuUtilizationNumber values for each VM (host). To determine the remaining OCPU capacity that can be allocated on a VM, subtract the ocpuUtilizationNumber value from the ocpuCapacityNumber value.

When you add a peer to a particular availability domain or fault domain, if the specified OCPUs value is greater than the remaining OCPU capacity on the VM in that domain, then a new VM is allocated. Otherwise, the existing VM is used to host the new peer. For domains that already have multiple VMs, if at least one VM has enough OCPU capacity, the peer is hosted there. Otherwise, a new VM is allocated.

Ordering Service
  • You can add an additional orderer node if you have selected to provision an Enterprise Edition instance.
REST Proxy
  • You can change the number of cluster replicas for your REST proxy.
Certificate Authority:
  • You can change the number of cluster replicas for your certificate authority.
Storage
  • Storage scaling is for Enterprise shapes only.
  • You can add storage in 1TB increments. Metering of storage is also in 1TB increments. You can't decrease storage once allocated.
  • The initial block size is 50GB for each manager VM in the cluster, and is increased in increments of 100GB.
  • When storage is scaled up on an instance, the block volume on each VM in the cluster will be increased by the same size. All VMs in a cluster will have block storage volumes of the same size at all times.
  • When new VMs are added as part of scaling peers and OSNs, every new VM will be brought to parity with existing VMs in the cluster by adding the same number and size of storage volumes as present in an existing VM. This additional storage will be taken from your platform storage pool (storage which has been purchased but not yet allocated to a VM). In situations when the platform storage pool does not have sufficient capacity to create the same number and size of block volumes for the new VM:
    • If the additional storage required is less than 0.5TB of the total purchased (metered) storage, we will add additional storage to enable creation of required volumes, and you will not be charged for additional <0.5TB of storage.
    • If the additional storage required is more than 0.5TB of the total purchased (metered) storage, you will be charged for additional storage units as applicable.

Monitor the Status of Your Blockchain Platform

You can use Oracle Cloud Infrastructure Console, command line, or REST APIs to check the status of your Oracle Blockchain Platform instances and any operations that are in progress.

Monitor Status using the Console

  1. In the Console, click Navigation menuin the top left corner.
  2. Under Developer Services, select Blockchain Platform.
  3. Select the compartment that contains the Oracle Blockchain Platform instances you're looking for.

    A list of all the instances in the compartment are displayed.

  4. Check the State column to determine the current status of your instance.
    • Creating: Instance is in the process of being created.
    • Active: Instance is running normally.
    • Updating: Instance is being updated. For example, in the process of scaling up or down.
    • Scaling: Instance is in the process of being scaled.
    • Inactive: Instance has been temporarily stopped or is stopping.
    • Failed: Instance isn't running due to an error.
    • Deleting: Instance is in the process of being deleted.

    Figure 3-1 Status of Blockchain Platforms


    Console view showing the State column for all Blockchain Platform instances.

  5. Click the name of your service to access the work request details.
    Use the Work Requests section to track the history and status of activities related to the instance. For example, work requests such as create, start, stop, scale, and so on.
    • Accepted: The request is in the queue to be processed.
    • InProgress: The work request started but isn't complete.
    • Succeeded: A work request record exists for this request and an associated WORK_COMPLETED record is in the state SUCCEEDED.
    • Failed: A work request record exists for this request and an associated WORK_COMPLETED record is in the state FAILED.
    • Canceling: The work request is in the process of canceling.
    • Canceled: The work request has been canceled.

    Figure 3-2 Status of a Blockchain Platform Instance


    Shows the list of work requests and their status.

Monitor Status using the Command Line

You use the work-request list and work-request get commands to get the current status of operations you perform on Oracle Blockchain Platform instances. If you want to cancel an operation, you use work-request delete. To check errors and access logs, you use work-request-error list and work-request-log list.

Refer to the Oracle Cloud Infrastructure CLI Command Reference for information about how to use these commands:

Monitor Status using the REST API

You use GetWorkRequest to get the current status of operations you perform on Oracle Blockchain Platform instances. If you want to cancel an operation, you use DeleteWorkRequest. To check errors and access logs, you use ListWorkRequestErrors and ListWorkRequestLogs.

Refer to the Oracle Cloud Infrastructure REST API Reference for information about how to use these operations:

Monitor Metrics

You can monitor the health, capacity, and performance of your Oracle Blockchain Platform resources by using metrics, alarms, and notifications.

Required IAM Policy

To monitor resources, you must be given the required type of access in a policy written by an administrator, whether you're using the Cloud console or the REST API with an SDK, CLI, or other tool. The policy must give you access to the monitoring services as well as the resources being monitored. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment you should work in. For more information on user authorizations for monitoring, see the Authentication and Authorization section for the related service: Monitoring or Notifications.

Available Metrics: oci_blockchainplatform

The metrics listed in the following table are automatically available for any Oracle Blockchain Platform that you create. You don't need to enable monitoring on the resource to get these metrics.

Metric Metric Display Name Unit Description
CpuUtilization CPU Utilization Percentage CPU utilization by the Blockchain Platform
NodesOcpuConsumption Nodes OCPU Consumption OCPU OCPU consumption by individual nodes in the Blockchain Platform
StorageUtilization Storage Utilization Percentage The percentage of provisioned storage capacity in use
CommitsProcessedByOrderer Commits Processed by Ordering Service Count Number of broadcast commits processed by the ordering service during the collection interval
EndorsementsProcessedByPeer Endorsements Processed by Peer Count Number of endorsements processed by peer during the collection interval
CommitsProcessedByPeer Commits Processed by Peer Count Number of commits processed by peer during the collection interval

View Default Metric Charts in the Console

Default metric charts use predefined service queries. You can select resources of interest and update the interval, statistic, and time range.

To view default metric charts for all Blockchain Platforms in a compartment:

  1. Open the navigation menu. Under Observability & Management, go to Monitoring and click Service Metrics.
  2. For Compartment, select the compartment that contains the instances that you're interested in.
  3. For Metric Namespace, select oci_blockchainplatform. The Service Metrics page dynamically updates the page to show charts for each metric that is emitted by the selected metric namespace.

Optionally, you can specify other dimensions to filter your displayed metrics. For more information, see To filter results and To select different resources in the Oracle Cloud Infrastructure documentation.

For more information about monitoring and notifications in Oracle Cloud Infrastructure, see Monitoring Overview and Notifications Overview in the Oracle Cloud Infrastructure documentation.

To view default metric charts for a specific Blockchain Platform instance:

  1. Open the navigation menu. Under Developer Services, select Blockchain Platform.
  2. Select the compartment that contains the instance that you're interested in, and click that instance name from the list of instances.
  3. On the Instance page, under Resources, click Metrics. The default metrics for your instance will be displayed.

Create Metric Queries in the Console

To create a query for a customized view of your metrics:

  1. Open the navigation menu. Under Observability & Management, go to Monitoring and click Metrics Explorer.

    The Metrics Explorer page displays an empty chart with fields to build a query.

  2. Fill in the fields for a new query.

    For more information, see Building Metric Queries in the Oracle Cloud Infrastructure documentation.

View Metrics By Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials in the Oracle Cloud Infrastructure documentation. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following APIs for monitoring: