5 Provision an Instance

Before You Create an Oracle Blockchain Platform Instance

Before you provision Oracle Blockchain Platform, decide if a developer or enterprise instance meets your needs.

Deciding Which Provisioning Shape to Use

When provisioning an instance, you choose between two configurations. Migration between these options isn't supported currently.

Configuration Features
Developer

Recommended use for this starter shape is development and evaluation.

  • Default configuration is a single platform VM running all other blockchain functions such as peers, orderers, CAs, console, REST proxy and an internal load balancer, and 1 chaincode runtime container VM for running chaincode. You can optionally choose to run the chaincode on a seperate VM.
  • 2 Fabric-CA nodes
  • 3-node single VM Kafka/Zookeeper cluster (Founder only)
  • Up to 14 Peer nodes
  • Dynamically managed chaincode execution containers
  • Console service for operations web user interface
  • REST proxy service for RESTful API
  • LDAP server integration for authentication and role management
  • Load balancer
Enterprise

Highly available instance configuration, suitable for small-to-medium production deployments of Founder and Participant instances with performance requirements in tens of transactions per second (TPS) single digit TPS rate.

  • Default configuration is 3 platform VMs running all other blockchain functions such as peers, orderers, CAs, console, REST proxy and an internal load balancer
  • 1 chaincode runtime container VM for running chaincode
  • 2 Fabric-CA nodes
  • 3-VM Kafka/Zookeeper cluster (Founder only) for high availability. You can optionally choose to reuse other VMs for these.
  • Up to 14 Peer nodes spread across separate virtual machines
  • Dynamically managed chaincode execution containers in an isolated virtual machine
  • Console service for operations web user interface replicated across separate virtual machines for high availability
  • REST proxy service for RESTful API
  • LDAP server integration for authentication and role management
  • Load balancer

Provision an Instance using the Blockchain Platform Manager

To create a blockchain founder or participant instance in Blockchain Platform Manager, use the Create New Instance wizard.

There are two types of Oracle Blockchain Platform instances you can provision:
  • Founder organization: a complete blockchain environment, including a new network to which participants can join later on.

  • Participant instance: if there is already a founder organization you want to join, you can create a participant instance if your credentials provide you with access to the network.

  1. In Blockchain Platform Manager, open the Instances page.
  2. Select Create Instance.
  3. Complete the following fields:
    Section Field Description
    General Instance Name

    Enter a name for your Oracle Blockchain Platform instance.

    The service instance name:

    • Must contain one or more characters.
    • Must not exceed 15 characters.
    • Must start with an ASCII letter: a to z.
    • Must contain only ASCII lower-case letters or numbers.
    • Must not contain a hyphen.
    • Must not contain any other special characters.
    • Must be unique within the identity domain.
    Description

    Optional.

    Enter a short description of the Oracle Blockchain Platform instance.

    Role

    Select Founder to create a complete blockchain environment. This instance becomes the founder organization and you can onboard new participants in the network later.

    Select Participant to create an instance that will join an existing blockchain network created elsewhere before this instance can be used.

    Configuration
    Select a provisioning shape which meets the needs of your deployment:
    • Developer
    • Enterprise
    Peers

    Specify the number of peer nodes to be initially created in this service instance. You can create between 1 and 14 peer nodes. You can create additional peer nodes in the Oracle Blockchain Platform console at a later time.

    Cluster Configuration Platform Host Add the fully qualified host name of the VM hosting Oracle Blockchain Platform. For Developer instances you need to provide one VM. For Enterprise instances you need to provide three VMs to create a high-availability cluster.
    Chaincodes Host Add the fully qualified host name of the VM hosting the chaincodes.
    Zookeeper/Kafka Host

    Add the fully qualified names of the VMs hosting the Zookeeper/Kafka orderer cluster (the platform hosts). Developer instances will have 1 VM, Enterprise will have 3 VMs to create a high-availability cluster.

    If you're using the same host as the platform you can select the checkbox instead of re-entering the host information.

    Additional Configuration Use External Load Balancer Select if you want to use an external load balancer instead of the one provided by Oracle Blockchain Platform Enterprise Edition.

    Enter the fully qualified domain name and port of the load balancer.

    Upload the TLS root CA certificate. The TLS root CA certificate must be named rootCA.zip and contain a single file named tls-ca.pem

    Enable TLS for Default Load Balancer If you want to use the load balancer provided by Oracle Blockchain Platform Enterprise Edition, select this option.
    Third Party CA Archive

    Optional.

    Oracle Blockchain Platform includes a certificate authority (CA), which is used to create self-signed certificates for all blockchain nodes in your instance

    If you want to use certificates from your own certificate authority and use the Oracle Blockchain Platform certificate authority as an intermediary CA, you can upload your CA archive. The certificate you upload will be used to sign the intermediary certificates for Oracle Blockchain Platform nodes, thus including them under your root CA chain.

    The archive is a zip file which contains the following files:
    • CA chain - named xxxca-chain.pem. The entire CA file sequence from the signing CA to the top-level CA should be present.
    • key - named xxxca-key.pem. The key should be a 256-bit elliptic curve key. The prime256v1 curve is recommended. The key should be an unencrypted private key in PKCS #8 format.
    • certificate - named xxxca-cert.pem. Must be in Base64 format. Must include the Subject Key Identifier extension.
    where xxx is an identifier of your choice. The archive must be less than 2MB.
  4. Verify that the details are correct, and click Confirm.
Once your instance has been created and is listed in the Instances list, you can launch the service console from the menu next to the instance name. Use the console to configure your network as described in Using Oracle Blockchain Platform.

Provision an Instance Using REST APIs

You can provision an Oracle Blockchain Platform instance using a REST API.

The following example shows how to create an Oracle Blockchain Platform instance using REST API:
curl -X POST \ 
-u <username>:<password> \ 
http://localhost:7070/api/v1/blockchainPlatforms/instances \
-H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \ 
-F 'payload={
"name": "obpinstance1",
"desc": "test instance",
"platformRole": "founder",
"configuration": "Developer",
"peer": 4,
"cluster": {
"platformHosts": [
"10.182.73.23",
"10.182.73.20"
],
"crcHosts": [
"10.182.73.23",
"10.182.73.20"
]
},
"additionalConfiguration": {
"instanceFQDN": "domain.host.com"
}
}'
  • name
    • Must contain one or more characters.
    • Must not exceed 15 characters.
    • Must start with an ASCII letter: a to z.
    • Must contain only ASCII lower-case letters or numbers.
    • Must not contain a hyphen.
    • Must not contain any other special characters.
    • Must be unique within the identity domain.
  • desc
    • Optional: Enter a description of the instance
  • platformRole
    • Must be set to developer or founder
  • configuration
    • Developer: A 1 Kafka orderer and 3 OCPU total in 1 VM
    • Enterprise: A 3 node Kafka cluster and 3 X VM
  • peer
    • Specify the number of peer nodes that will be initially created in this service instance.
    • 1 to 14 peer nodes can be created.
  • cluster
    • Enter the information for your cluster:
      • platformHosts: the VMs hosting your platform cluster
      • crcHosts: the VMs hosting the Kafka/Zookeeper cluster
  • instanceFQDN
    • The fully qualified domain name of your external load balancer. This is used exclusively for external load balancers - if you're not using an external load balancer, you don't need to specify this parameter.

Postrequisites When Using an External Load Balancer

When provisioning your instance, if you are using an external load balancer you must have selected this during the provisioning steps and uploaded the TLS root CA certificate as described in Provision an Instance using the Blockchain Platform Manager or Provision an Instance Using REST APIs.

Once this is done you can configure your load balancer. The blockchain instance will be listening on a variety of ports which will need mapped to external ports. The ports used will vary depending on the configuration; namely the amount of peers.
  1. Obtain the complete list of ports needing mapping for your instance. Open the Instance Details page for your instance on Blockchain Platform Manager, then click LBR Port Map.

    Record the ports listed.

  2. In your load balancer, do a mapping as shown in the Nginx syntax example below, where my.blockchain.example.com is the FQDN of the blockchain instance (internal side):
    ...stream {
        upstream port1 {
        server my.blockchain.example.com:10001;
      }
      server {
            listen *:10003 ssl;
            ssl_certificate /etc/nginx/server.pem; # use your own certificate/key
            ssl_certificate_key /etc/nginx/serverkey.pem;
            proxy_pass port1;
      }
    ...
  3. Repeat for every port listed in the port map.

Note:

If at some point in the future you scale out your instance by adding new peers, remember to map those new peers using the steps above.

High Availability

To achieve high availability in an Enterprise-shaped instance with distinct VMs, you can configure the external load balancer to add a list of all platform VMs in the cluster (the Kafka and ZooKeeper VMs are already highly available) as an upstream (backend) list.

For example, with a cluster of VMs with hostnames
  • a.example.com
  • b.example.com
  • c.example.com
the configuration snippet becomes:
...
stream {
upstream rest_proxy_backend_servers
{ 
    server a.example.com:10001; 
    server b.example.com:10001; 
    server c.example.com:10001; 
}
server
{ 
    listen *:10003 ssl; 
    ssl_certificate /etc/nginx/server.pem; # use your own certificate/key 
    ssl_certificate_key /etc/nginx/serverkey.pem; 
    proxy_pass rest_proxy_backend_servers; 
}
...
stream { 
upstream peer0_backend_servers
{
    server a.example.com:10036;
    server b.example.com:10036;
    server c.example.com:10036;
} 
server {
    listen *:10036 ssl;
    ssl_certificate /etc/nginx/server.pem; # use your own certificate/key
    ssl_certificate_key /etc/nginx/serverkey.pem;
    proxy_pass peer0_backend_servers; 
}
...

Each externally available port in the instance cluster is published on each VM and routes to the proper service automatically (console, membership/CA, orderers, peers, REST proxy).

Ensure that all ports listed via the LBR Port Map button are routed in this way.

After provisioning a 3 VM cluster, run the following commands on the swarm manager (which should be the first machine in the cluster), where the control plane and component manager run:
$ docker node ls 
This will return the list of nodes in the cluster. For example:
 [oracle@dhcp-10-144-63-180 ~]$ docker node ls
ID                            HOSTNAME                                   STATUS   AVAILABILITY  MANAGER STATUS  ENGINE VERSION
fz1ksoxysyorz754x0hswnird     dhcp-10-144-62-149.usdhcp.oraclecorp.com   Ready    Active                        18.09.1-ol
rayhna7vdiup5p7tkmxxepyex *   dhcp-10-144-63-180.usdhcp.oraclecorp.com   Ready    Active        Leader          18.09.1-ol
For each node that has no manager status, promote the nodes using a command similar to the following example:
$ docker node promote dhcp-10-144-62-149.usdhcp.oraclecorp.com

Ensure that a minimum of three nodes are promoted in this manner.