Getting started with IBM Blockchain Platform for IBM Cloud
ATTENTION!! IBM Blockchain Platform SaaS Edition has been replaced by IBM Support for Hyperledger Fabric!! IBM Blockchain Platform SaaS Edition will no longer be supported after July 31, 2023. Customers have been directed to migrate their networks by July 31, 2023. After this date, IBM Blockchain Platform SaaS networks that are not migrated to IBM Support for Hyperledger Fabric will be at risk for potential security vulnerabilities. A migration tool is provided from your console, and the disruption to your network is minimal. See Migrating to IBM Support for Hyperledger Fabric for details.
IBM® Blockchain Platform for IBM Cloud includes the IBM Blockchain Platform console, a user interface that can simplify and accelerate your journey to deploy and manage blockchain components. This tutorial describes how to get started with IBM Blockchain Platform for IBM Cloud and use the console to deploy and manage blockchain components in your Kubernetes cluster on IBM Cloud. To learn more about Kubernetes see this overview.
Target audience: This topic is designed for system administrators who are responsible for setting up a Kubernetes cluster on IBM Cloud and for deploying IBM Blockchain Platform.
If you are interested in learning more about how to use IBM Blockchain Platform on Red Hat OpenShift Container Platform, Red Hat Open Kubernetes Distribution (OKD), or Kubernetes, see Getting started with IBM Blockchain Platform 2.5.4.
If you are an experienced Hyperledger Fabric customer and are interested in learning more about how to use the IBM Blockchain peer, CA, orderer, and smart contract containers images, see Using the IBM Blockchain images .
After you link your IBM Blockchain Platform to your Kubernetes cluster on IBM Cloud, you can launch the console to create and manage your blockchain components and experience the following important benefits:
- Control: You control and manage your blockchain components and certificates from one central console. Deploy only the components needed for your business and add more as your need grow.
- Flexible Kubernetes based deployment: You can take advantage of the compute (CPU, memory, storage) options for your Kubernetes cluster and leverage built-in HA and DR options.
What is the Blockchain Service?
The following diagram illustrates the three elements of the IBM Blockchain Platform:
-
IBM Blockchain Platform Console (UI): This is the console that allows you to create and manage your blockchain components. After you provision a service instance in IBM Cloud, you can deploy an instance of the IBM Blockchain console and link it to your Kubernetes cluster on IBM Cloud. Then you can use the console to create and manage your blockchain components in your Kubernetes cluster. There is no charge for the console.
-
Hyperledger Fabric Components: The console is used to create and manage blockchain components that are based on Hyperledger Fabric v2.2.10 Certificate Authority, peer, and ordering service images. These components are deployed into your Kubernetes cluster and storage is provisioned for them using the
default
storage class when they are deployed.
Considerations
Before you deploy the console, ensure that you understand the following considerations:
- IBM Blockchain Platform for IBM Cloud is built with Hyperledger Fabric v2.2.10.
- You have the option to link your IBM Blockchain Platform service instance to a free Kubernetes cluster for evaluation of the offering, however capacity and performance are limited, none of your data can be migrated, and the cluster is deleted after 30 days.
- You are responsible for the management of health monitoring, security, and logging of your Kubernetes cluster. See this information for details on what IBM Cloud manages and what you are responsible for.
- You are also responsible for monitoring the resource usage of your Kubernetes cluster by using the Kubernetes dashboard. If you need to increase storage capacity of your cluster, see this information on how to modify your existing volume:
- You are responsible for managing and securing your certificates and private keys. IBM does not store your certificates in the Kubernetes cluster.
- IBM Blockchain Platform is available in select regions. Refer to this topic on IBM Blockchain Platform locations for an updated list.
- IBM Blockchain Platform is compatible with a Kubernetes cluster on IBM Cloud running Kubernetes v1.24 - v1.26.
- The default storage that is pre-selected for you when you provision a Kubernetes cluster in IBM Cloud is
Gold
. If you do not want to use the default File Storage that is pre-selected for you when you provision a Kubernetes cluster in IBM Cloud, you can provision storage of your choice. See this topic on Persistent storage considerations to learn more. - If you decide to include IBM Cloud multi-zone support in your Kubernetes cluster, you must provision your own storage. See Using Multizone (MZR) clusters with IBM Blockchain Platform for more details.
- Kubernetes clusters that are configured with private VLANs are not supported.
Video tutorial
Watch the following video series to learn more about the IBM Blockchain Platform console and how you can get started to deploy IBM Blockchain Platform for IBM Cloud.
Before you begin
Before you begin:
- Ensure that you have an IBM Cloud paid account. If you do not have an account:
- Click the Sign up button.
- After you create a free trial account, upgrade it to a Pay-As-You-Go type by going to Manage > Billing and Usage > Billing in the IBM Cloud console, and clicking Add Credit Card.
- Ensure that the user has both Administrator and Manager roles for the Kubernetes cluster that they will link to their blockchain service instance. See these steps on how to assign Kubernetes access roles for more information.
When you plan to use the service instance in the context of a broader organization-wide solution, it is recommended that the participating organizations use a functional email address to create their network. In this case, access to the network does not depend on any single individual's availability.
-
If you plan to use an existing Kubernetes cluster on IBM Cloud, ensure the version of Kubernetes it is running is between v1.24 - v1.26. For more information about how to determine what version of Kubernetes your cluster is running and how to upgrade the version, see Updating the Kubernetes version of your cluster.
-
If you plan to use a Hardware Security Module (HSM) to generate and store the private key for your peer and ordering nodes, you can configure the HSM before you deploy the platform. Along with deploying the HSM device itself, in order for the blockchain components to access the HSM partition, you also need to publish an HSM client image to a container registry. If you decide to publish an HSM client image to a container registry, you can enable HSM support for the platform by providing the image URL when you link the service to your cluster. See the instructions in Configuring a node to use a Hardware Security Module to learn how to deploy the HSM and publish the HSM client image. If the HSM device is not yet available, you can always come back later and enable the HSM support for the platform when it is ready.
-
Zero downtime is an important goal of your blockchain network. Review the topic on High Availability for considerations when configuring your Kubernetes cluster and blockchain components.
-
If you plan to use a Kubernetes cluster that contains multiple zones, ensure that
VLAN spanning
is enabled in your account. This setting allows worker nodes to communicate between zones. -
The user who links the service to the Kubernetes cluster must have Storage Manage permissions. From the IBM Cloud dashboard, navigate to Manage > Access (IAM), then choose Users, and click the user who will link the service to the Kubernetes cluster. Click the Classic infrastructure tab, expand the Services twistie, and select Storage Manage. Click Apply to add this permission for the user.
Browsers
The IBM Blockchain Platform console has been successfully tested on the following browsers:
- Chrome Version 111.0.5563.64 (Official Build) (x86_64)
- Safari Version 16.3 (18614.4.6.1.6)
- Firefox 110.0.1 (64-bit)
Resources required
Cluster size recommendations
When you link your IBM Blockchain Platform console to a Kubernetes cluster on IBM Cloud, you need to ensure that your Kubernetes cluster meets the minimum hardware resource requirements:
Kubernetes cluster type | Use case | CPU | RAM | Worker nodes |
---|---|---|---|---|
Standard (Recommended) | Suitable for MVPs | 4 (Shared) | 16 GB (Shared) | multiple |
Free** | Suitable for evaluation | 2 | 4 GB | 1 |
** Preview the IBM Blockchain Platform at no charge for 30 days when you link your IBM Blockchain Platform service instance to an IBM Cloud Kubernetes free cluster. Performance will be limited by throughput, storage and functionality. IBM Cloud will delete your Kubernetes cluster after 30 days and you cannot migrate any nodes or data from a free cluster to a paid cluster. Also note that when components are deployed to a free cluster, the resource allocation for the nodes is sized smaller than a paid cluster.
These resources are sufficient for testing and experimentation. The Build a network tutorial, in which you create two peers, two CAs, and a single node ordering service, takes up approximately 1.95 CPU. A five node ordering service requires 1.75 CPU by itself. Therefore, if you plan to deploy a five node ordering service, you should not deploy a Kubernetes cluster with a 2 CPU single worker node as the ordering service will not fit comfortably with other nodes. We recommend a cluster with nodes of at least 4 CPU. The more worker nodes you add, the easier your cluster will be able to handle your deployments.
Paid clusters
Production level deployments of the IBM Blockchain Platform will be deployed to a paid cluster of IBM Cloud Kubernetes Service. The size and configuration of this cluster will depend on the needs of your particular use case. Bigger deployments will necessarily need to be deployed on bigger clusters. How much bigger your cluster is than your projected deployment is up to you. Having at least some headroom is desirable, as it will allow peers and ordering services to be a part of additional channels and take on higher throughput without having to deploy additional resources into your Kubernetes cluster before adjusting the size of your nodes. For more information about how these values are adjusted, see Reallocating resources.
Creating an initial deployment of sufficient size to allow growth is particularly important for users who will choose to not use the Kubernetes Service or OpenShift autoscaler, which can take on some of the burden of deploying additional nodes and pods for the user.
While it is simpler to have enough resources deployed to IBM Cloud Kubernetes Service and be able to expand your pods and worker nodes as you see fit without having to increase your Kubernetes cluster deployment first, bigger Kubernetes cluster deployments will cost more money. Users will have to consider their options carefully and recognize the tradeoffs they are making regardless of the option they choose.
For a sense of how much storage and compute you will need in your cluster, refer to this chart, which contains the current defaults for the peer, ordering node, and CA:
Component (all containers) | CPU** | Memory (GB) | Storage (GB) |
---|---|---|---|
Peer (Hyperledger Fabric v1.4) | 1.1 | 2.8 | 200 (includes 100GB for peer and 100GB for state database) |
Peer (Hyperledger Fabric v2.x) | 0.7 | 2.0 | 200 (includes 100GB for peer and 100GB for state database) |
CA | 0.1 | 0.2 | 20 |
Ordering node | 0.35 | 0.7 | 100 |
Operator | 0.1 | 0.2 | 0 |
Console | 1.2 | 2.4 | 10 |
Note that when smart contracts are installed on peers that run a Fabric v2.x image, the smart contract is launched in its own pod instead of a separate container on the peer, which accounts for the smaller amount of resources required on the peer.
If you plan to deploy a five node Raft ordering service, note that the total of your deployment will increase by a factor of five. So a total of 1.75 CPU, 3.5 GB of memory, and 500 GB of storage for the five Raft nodes. A 4x16 Kubernetes two worker node cluster is minimally recommended to allow plenty of CPU for the Raft cluster and any other nodes you deploy.
Persistent storage considerations
IBM Blockchain Platform requires persistent storage for each CA, peer, and ordering node. When you deploy a standard Kubernetes cluster in IBM Cloud, it uses a pre-configured storage class that is backed by IBM Cloud File Storage. You have the option to upgrade your storage class, change your backing storage, or use third-party services.
Every cluster on your Kubernetes cluster on IBM Cloud comes with predefined, default
storage class that is used to provision persistent storage on IBM Cloud. When you deploy a blockchain node to that cluster by using the IBM Blockchain
Platform console or the APIs, the node uses this default
storage class to dynamically provision the amount of storage that you specify on IBM Cloud.
For IBM Cloud Kubernetes service, the default
storage class is Gold
File Storage backed by Endurance File Storage. See Deciding on the File Storage configuration for more details. OpenShift clusters default to Gold
Block Storage.
If you need to change your default storage class, see Ordering File Storage with pre-defined IOPS Tiers (Endurance) and then follow instructions to configure a custom storage class.
Provision persistent storage
If you are linking to a Red Hat OpenShift cluster in IBM Cloud, review the topic on Planning highly available persistent storage. If you are linking to an IBM Cloud Kubernetes Service cluster, you can choose from several Kubernetes storage options and decide on the storage type that best fits your use case. In both cases, you need to provision persistent storage. Be aware that you are charged separately for your storage usage, so you can factor in the cost of the various storage options when you make your selection. All of the predefined storage classes in your Kubernetes cluster on IBM Cloud use File Storage as the backing storage. For more information, see IBM Cloud File Storage pricing.
Multizone-capable storage
If your Kubernetes cluster is configured with SDS (Portworx) storage, you can leverage multizone-capable storage for your nodes. Without multizone-capable storage, if an entire zone goes down, any blockchain nodes in that zone cannot automatically come up in another zone because their associated persistent storage is unavailable in the failed zone. When multizone-capable storage is configured for high availability, if a zone failure occurs, the nodes can come up in another zone, with their associated storage intact, ensuring high availability of the node. To learn more about multizone-capable storage, see the comparison of persistent storage options for multizone clusters on OpenShift or IBM Cloud Kubernetes service. When you deploy a peer, ordering service, or ordering node, select the advanced deployment option labeled Deployment zone selection and then select Across all zones to configure the component for this high availability capability.
Configuring a custom storage class
If you want to use Performance File Storage, or Portworx as backing storage, you must create
a customized storage class for your cluster. Read about how to add a storage class for Red Hat OpenShift clusters or IBM Cloud Kubernetes service clusters. You can then make the custom storage class the default
storage class by running the following command:
kubectl patch storageclass <storageclass> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
Replace <storageclass>
with the name of your storage class.
After you deploy blockchain nodes to your cluster, you should not change the default
storage class. This will result in losing the storage for the CAs, peers, and ordering nodes that are already deployed. Therefore, you need to
decide on your storage before you deploy any blockchain nodes.
If you need to increase storage capacity of your cluster, see this information on how to modify your existing volume:
Using Multizone (MZR) clusters with IBM Blockchain Platform
In regions where it is offered, multizone support is pre-selected by default when you create a standard Kubernetes cluster on IBM Cloud. Although not required, this capability provides for high availability of your nodes in case any one zone, or data center, goes down. If your cluster includes multizone support, you need to bring your own storage solution. You can choose from several persistent storage options.
If you are setting up an IBM Blockchain Platform network in an MZR cluster and want your components to eventually fail over between data centers, you should select Portworx as your storage type. Otherwise, if you use File Storage for your node in your MZR cluster and the zone fails, you will need to provision that component again later. Currently, if a data center (or zone) goes down, the node will not automatically come up in another zone, regardless of the storage type that is used for the node. However, if one of the nodes fails in a single zone, it will automatically failover to another node in the same zone regardless of the storage type that is being used for that node.
After you create the storage class, run the kubectl patch storageclass
command above to set the storage class of the multizone region to be the default
storage class.
Pricing and Billing information
- See Pricing if you need to revisit the IBM Blockchain Platform pricing information.
- Your current IBM Cloud usage information is available on your usage tile of the IBM Cloud dashboard and your bill is visible under billing information. See this topic on Billing for more details about how IBM Blockchain Platform billing works.
Choose your deployment process
From your IBM Cloud account, you can deploy the IBM Blockchain Platform service from either the IBM Cloud Catalog or the Red Hat Marketplace.
- IBM Cloud Catalog Use the IBM Cloud Catalog to deploy blockchain to an IBM Kubernetes service or OpenShift cluster in IBM Cloud. With this software-as-a-serviceA model of software deployment whereby software including business processes, enterprise applications, and collaboration tools, are provided as a service to customers through the cloud. option, IBM manages the maintenance and the updates to the console for you, but you can choose when to update your blockchain components.
- Red Hat Marketplace OpenShift customers who are already familiar with the OpenShift Container (OC) CLIA computer interface in which the input and output are text based. and the Red Hat Marketplace may prefer to use this option. Note that with this option, you are responsible for the maintenance of your console and blockchain components.
- Multicloud Not running an OpenShift or Kubernetes cluster in IBM Cloud? The IBM Blockchain Platform 2.5.4 can be installed on your OpenShift or Kubernetes cluster in your cloud or on-prem. With this option as well, you are responsible for the maintenance of your console and blockchain components.