Block Chain

IBM Cloud
IBM Blockchain Platform

Product guide
Edition notices
This PDF was created on 2023-02-28 as a supplement to IBM Blockchain Platform in the IBM
Cloud docs. It might not be a complete set of information or the latest version. For the latest
information, see the IBM Cloud documentation at
https://cloud.ibm.com/docs/blockchain/index.html.
Getting started
Getting started with IBM Blockchain Platform
IBM® Blockchain Platform provides a managed and full stack blockchain-as-a-service (BaaS) offering that allows you to deploy
blockchain components in environments of your choice. Clients can build, operate, and grow their blockchain networks with an
offering that can be used from development through production.
Important: Before you use an IBM Blockchain Platform offering, read the technical and support information in the
Disclaimer section.
Which IBM Blockchain Platform offering is right for your business?

IBM Blockchain Platform provides different offerings that allow you to deploy your network in the environment of your choice.
You need to decide if you want to deploy the IBM Blockchain Platform 2.5.3 or if you want to use the IBM Blockchain Platform
for IBM Cloud.
IBM Blockchain Platform for IBM Blockchain Platform for
anywhere (2.5.3) IBM Cloud
Where do you want to deploy the platform? Multiple Kubernetes distributions A Kubernetes cluster on IBM
on a private, public, or hybrid Cloud
multicloud
See Supported
See Supported Platforms) configuration
What are my deployment options?

Full platform Full platform
Only IBM Blockchain
images
How is it billed? Contact us for pricing $0.29 USD per allocated

CPU hour
Can I connect with peers in other clouds? Yes Yes
Can my data center be on-prem and behind a Yes No

firewall?
Can I use a console UI to deploy and manage my Yes Yes

blockchain components?
Are APIs available for node management? Yes Yes
I am an experienced Fabric customer. Are peer, CA, Yes No

orderer, and smart contract images available and
supported?
Where can I learn more? See About IBM Blockchain See About IBM Blockchain
Platform 2.5.3 Platform for IBM Cloud
Ready to get started? See Step one: Install the IBM See Getting started with
Blockchain Platform IBM Blockchain Platform for
IBM Cloud
Table 1. Which offering is right for your business?
IBM Blockchain Platform 3

Have questions and want to speak to an IBM Blockchain Platform expert? Schedule a consult now to learn more about how
blockchain can transform your business.
IBM Blockchain images

Your purchase of IBM Blockchain Platform 2.5.3 includes an entitlement to images for peer, Certificate Authority,
ordering service, and smart contract containers that are signed by IBM. The images are based on the open source
Hyperledger Fabric code base and contain a number of enhancements. The images are bundled with support from IBM.
The IBM Blockchain images do not include the IBM Blockchain management console or operator. This offering is intended
for experienced Fabric users with existing Fabric deployments. For more information, see IBM Blockchain images for
Hyperledger Fabric.
Next steps
After you deploy IBM Blockchain Platform in the environment of your choice, you can set up the network with consortium, nodes,
channels, smart contracts, and start transactions on it. For more information, see the task topics under the HOW TO section in
the left navigation of this documentation.
Getting support
IBM offers various support options on IBM-implemented blockchain solutions. For more information about IBM Blockchain
Platform support, see Getting support.
Getting started with IBM Blockchain Platform for IBM Cloud

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.3.
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:
Figure 1. The IBM Blockchain Platform components
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 v1.4.12 and v2.2.5 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 v1.4.12 and v2.2.5.
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:
IBM File Storage
Portworx
Block storage
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.23 - v1.24.
The default storage that is pre-selected for you when you provision a Kubernetes cluster in IBM Cloud isGold. 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:
1. Click the Sign up button.
2. After you create a free trial account, upgrade it to aPay-As-You-Go type by going to Manage > Billing and Usage >
Billing in the IBM Cloud console, and clicking Add Credit Card.
3. 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.
Tip: 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.23 - v1.24. 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 haveStorage 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 100.0.4896.127 (Official Build) (x86_64)

Safari Version 15.4 (16613.1.17.1.13, 16613)
Firefox 99.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
Table 1. Recommended cluster size on Kubernetes cluster on IBM Cloud
** 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.
Note: 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 Storage (GB)

(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
Table 2. Recommended resources for nodes on IBM Blockchain Platform for IBM Cloud
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.
Tip: 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.
Important: 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.
Important: 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:
IBM File Storage

Portworx
Block storage
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.
Note: 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-service 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) CLI 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.3 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.
Deployment options
Deploy from IBM Cloud

Learn how to get started with IBM Blockchain Platform for IBM Cloud from the IBM Cloud Catalog.
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.

Deploy a Kubernetes cluster on IBM Cloud
If you don't already have an existing Kubernetes cluster on IBM Cloud in a supported region, you must create one. For
information about locations where the IBM Blockchain Platform can be deployed, see Supported regions.
In the Cloud Catalog, find the Kubernetes Service tile and click it. Note that you have two types of Kubernetes clusters you can
deploy: an IBM Kubernetes Service cluster or an OpenShift cluster. The IBM Blockchain Platform can be linked to either one.
Your choice of cluster will be based on your use case.
For more information about the IBM Kubernetes Service, see Getting started with IBM Cloud Kubernetes Service.
For more information about OpenShift, see About the OpenShift Kubernetes Engine.
As both IBM Kubernetes Service clusters and OpenShift clusters are based on Kubernetes, you will find that many of the
underlying decisions about hardware and storage types will be the same regardless of which cluster provider you choose. Note
that the Kubernetes version of the cluster you deploy must be v1.23 - v1.24 to be compatible with the IBM Blockchain Platform.
Note that if you want high availability or disaster recovery, you will need to make a decision about the storage class you are
using. The default storage class on the cluster will be used by the dynamic provisioning. So, customers can set any storage
class as the default. For more information, see Deciding on the file storage configuration.
Free IBM Kubernetes Service clusters

The IBM Kubernetes service offers a free cluster that can be used for 30 days. Note that the free cluster offers limited storage
and transaction throughput, and that it is not possible to migrate data from free clusters to paid clusters. For more information
about the differences between the free and paid Kubernetes clusters on IBM Cloud, see Comparison of free and standard
clusters.
For instructions on what to do when your Kubernetes cluster expires, see this topic on Kubernetes cluster expiration.
Create an IBM Blockchain Platform service instance in IBM Cloud

After you have deployed a Kubernetes cluster on IBM Cloud, you're ready to create an instance of IBM Blockchain Platform for
IBM Cloud.
Creating an IBM Blockchain Platform service instance is a two step process.
Create and name the instance.

Link the instance to your cluster in IBM Cloud.
Step one: Create and name the instance

1. Locate the Blockchain Platform in the IBM Cloud Catalog, or search for Blockchain on the IBM Cloud Catalog page.
2. We recommend that you rename the Service name for your instance so you can recognize it easily in the future.
3. Choose your region from the drop-down list under Select a region. For a list of available regions, see Regions.
4. You can leave the resource group and tags fields unchanged.
5. Click Create to provision the service instance.
Step two: Link the instance to your Kubernetes cluster on IBM Cloud
After you click Create to create your service instance, you'll be taken to the panel where you can link your service instance to
your cluster.
If you have not already created a Kubernetes cluster in IBM Cloud, clickCreate a Kubernetes cluster on IBM Cloud. You will be
taken to the catalog page and have to follow the process described in Deploy a Kubernetes cluster on IBM Cloud.
If you already have a cluster, you can link your service instance to it by clickingLink a Kubernetes cluster on IBM Cloud and

selecting your existing cluster from the drop-down list. If your Kubernetes cluster is not visible in the drop-down list, it could be
caused by the following conditions:
The cluster creation process can take up to 60 minutes to complete. If you created a cluster, allow some extra time until
the state of your cluster becomes Normal.
Clusters that are outside the supported regions are not visible and cannot be used.
Check to make sure you are not using the ESR version of Firefox. If you are, switch to another browser such as Chrome and
retry.
If you have a multi-zone region ( MZR) cluster you need to enable VLAN spanning.
If your cluster is available, select it and click Next. It might take a few minutes for the console to finish being linked to your
cluster. When the linking process has finished, click Launch the IBM Blockchain Platform console to open the console. You are
now ready to start exploring the console.
Blockchain component deployment

The following illustration shows how the IBM Blockchain Platform components are deployed to the Kubernetes
cluster assuming Hyperledger Fabric v2.x images are used by the peer.
Figure 2: Deploying the IBM Blockchain Platform to a Kubernetes cluster on IBM Cloud.
Pod: When each Certificate Authority, peer, ordering service, or smart contract is deployed, a new Pod is created in a
worker node in your cluster. Every time you deploy a smart contract, a new pod is launched for the smart contract.
App containers: Containers are created inside the pods for each node that is deployed.
Persistent Storage: Storage for each node is dynamically provisioned from the Kubernetes clusterdefault storage class
every time a node is deployed.
The following illustration shows how the IBM Blockchain Platform components are deployed to the Kubernetes
cluster assuming Hyperledger Fabric v1.4 images are used by the peer.
Figure 3: Deploying the IBM Blockchain Platform to a Kubernetes cluster on IBM Cloud.
Pod: When each Certificate Authority, peer, or ordering service is deployed, a new Pod is created in a worker node in your
cluster.
App containers: Containers are created inside the pods for each node that is deployed.
Persistent Storage: Storage for each node is dynamically provisioned from the Kubernetes clusterdefault storage class
every time a node is deployed.
(Optional) Add additional users to the console

By default, the console uses IBM Cloud Identity and Access Management (IAM) as the IBM Cloud identity service provider. Your
IBM Blockchain Platform console is provisioned by configuring the email address of the IBM owner as the Administrator of the
console. As an Administrator, this user is authorized to grant other users access to the console via their email addresses. See
these instructions on how to add and remove users from the console for more information.
Next steps
Before you create any nodes, you need to decide on the storage plug-in for your Kubernetes cluster. If you are just getting
started and trying things out, Bronze file storage is suitable. However, if your cluster is running Kubernetes v1.19 or
higher, Gold File Storage is preselected for your cluster by default. To change the default storage for your cluster, see this
topic on Persistent storage considerations to learn more.
Now that your console is ready to use, you can go ahead to the Build a network tutorial. Consider bookmarking the URL of
your console so you can come back at a later time if needed. Otherwise, you can follow the steps in the Post-install

instructions to get back to it from your browser.
Updating the Kubernetes version of your cluster

If you use an existing IBM Cloud Kubernetes service cluster, ensure that it is running Kubernetes v1.23 - v1.24.
Important: Before upgrading to Kubernetes version v1.23 - v1.24, ensure that you have migrated to Kubernetes ingress
controllers.
You can check the Kubernetes version of your cluster in the Kubernetes clusters page on IBM Cloud, which lists all your clusters
in a table.
For instructions on how to update Kubernetes, see Updating clusters, worker nodes, and cluster components. For the list of IBM
Cloud Kubernetes Service supported versions and expiration dates see the release history.
You must wait for the update to complete before you can resume the IBM Blockchain Platform deployment.
How to assign Kubernetes access roles

The user who links the blockchain service instance to the Kubernetes cluster must have the Administrator and Manager
roles in Kubernetes. To configure this access you must complete the following steps:
$ 1. In the IBM Cloud dashboard, click the **Manage** drop-down list, then **Access (IAM)**.
2. In the left navigation menu, click **Users** and click the ID of user who will link the service
instance to the Kubernetes cluster.
3. Click **Access Policies**, then **Assign access**.
4. Click the tile **Assign access to resources**.
5. In the Services drop-down list, select **Kubernetes Service**.
6. Check the **Administrator** and **Manager** roles for this user.
7. Click **Assign**.
For more information about Kubernetes access control, see how to pick the right access policy and role for your users.
Post-install instructions
After you deploy your console, you can click the Launch the IBM Blockchain Platform button to open the console in your
browser. You can add the console URL as a bookmark to your browser.
Returning to your console from IBM Cloud

If you don't have the console URL, you can find it from your IBM Cloud dashboard.
1. In your browser, open IBM Cloud Resource list. You need to log in with your IBM ID.
2. Your IBM Blockchain Platform service instance is visible under the Services twistie. Locate the IBM Blockchain Platform
service instance that you deployed and click it.
3. On the subsequent panel, click Manage in the left navigation and then click Launch the IBM Blockchain Platform.
Your console opens in your browser.
Deleting a service instance

When you no longer need your service instance it can be deleted from your Kubernetes cluster to free up resources. You can use
the IBM Cloud dashboard to delete your IBM Blockchain Platform service instance.
Important: If the service instance contains organizations that are participating in an active network, you should remove
the organization from the network before you delete the service instance. See Removing an organization for more details.

1. In your browser, open IBM Cloud Resource list. You need to log in with you IBM ID.
2. Under the Services twistie, locate the service instance you want to delete and clickDelete on the Actions menu.
Important: Choose this option carefully. If you delete a service instance, the storage associated with each node is
deleted and cannot be restored. All your ledger data will be deleted.
If your service instance deletion fails, it could be because the Kubernetes cluster is not accessible. If this occurs, open a support
ticket to request the service instance deletion.
Deploy from Red Hat Marketplace

The Red Hat Marketplace can be used to deploy the IBM® Blockchain Platform 2.5.3 operator onto a Kubernetes cluster on
OpenShift Container Platform 4.4+. This operator deploys instances of the certificate authority (CA), peer, ordering nodes and
the IBM Blockchain Platform console that uses to manage the blockchain components on your network. This deployment option
is available for OpenShift clusters that are running in IBM Cloud or your cloud.
What is Red Hat Marketplace?

Red Hat Marketplace is available directly from your OpenShift web console. It provides an open cloud catalog that makes it
easier to discover and access certified software for container-based environments in public clouds. With automated deployment,
software is immediately available to deploy on any Red Hat OpenShift cluster, providing a fast, integrated experience. Discover
and buy certified software, and quickly deploy. Access open source and proprietary software, with responsive support,
streamlined billing and contracting, simplified governance, and single-dashboard visibility across clouds. Built in partnership by
Red Hat and IBM, this marketplace helps organizations deliver enterprise software and improve workload portability.
Red Hat Marketplace provides a simplified alternative method for deploying an instance of the IBM Blockchain Platform to your
cluster instead of the manual deployment steps or by using Ansible playbook scripts.
With just a few simple steps, you can get started with the IBM Blockchain Platform. After you install the operator to your
OpenShift project, you can create a subscription that allows you to deploy the blockchain console UI.
Important: Currently, you cannot deploy certificate authorities (CAs), peers, and ordering nodes directly, then, use the
console to deploy those nodes instead. This tutorial includes only instructions for installing the console.
To learn more about the Marketplace see the Red Hat documentation.
Limitations
IBM Blockchain Platform 2.5.3 is supported on Red Hat OpenShift 4.4+.
You are responsible for the management of health monitoring, logging, and resource usage of your blockchain
components.
IBM Blockchain Platform is not supported on OpenShift Online.
Mutual TLS is not supported between your applications and your blockchain nodes.
You cannot use the extended support release(EMC Symmetrix for R) version of Firefox to log in to the IBM Blockchain
Platform console.
Before you begin
Note: You must have the cluster administrator role to install the operators from the Red Hat Marketplace.
1. These instructions assume you already have a Kubernetes cluster available in OpenShift Container Platform v4.4+ and
that you created a project for your IBM Blockchain deployment. Unsure how to create a project? See Create a project for

your IBM Blockchain Platform deployment.
2. Browse to the Red Hat Marketplace and log in or create a new account.
3. Follow the instructions to register your OpenShift cluster with the Red Hat Marketplace.
4. When prompted Would you like to go back to the Red Hat Marketplace now? [Y/n] , type Y to retrieve the Red
Hat Marketplace page in your browser.
5. Click My software > Visit the Marketplace.
6. In the search bar, type blockchain to load the blockchain tile.
7. Click Purchase to get started. From the Purchase complete page, click Install now. This installs the IBM Blockchain
Platform operator into your cluster. Note that during the installation process you are required to select which OpenShift
project to deploy the operator to from the Namespace scope drop-down. After the operator is installed, your cluster
connects back to Red Hat Marketplace and then becomes a target cluster for installing and managing the operator from
Red Hat Marketplace. You can deploy the operator multiple times across different clusters as long as they have registered
with the Red Hat Marketplace. When selecting a namespace for operator installation, All namespaces on the cluster is
selected by default—you must change this default selection to a specific namespace in the clusterto make operator
and Fabric components run in a dedicated namespace.
Figure 1. Install the operator in the openshift-operators namespace
8. The Console and Fabric components can be installed in any namespace.

Figure 2. Console and Fabric components can be installed in any namespace
9. Next, update the Security Context Constraint command settings to use the Fabric and Console namespaces.
Figure 3. Update Security Context Constraint command settings to use the Fabric and Console namespaces.
10. If your OpenShift cluster is behind a firewall, see Deploy from Red Hat Marketplace (airgap installation).
11. Continue to Step one: Apply the Security Context Constraint.
Step one: Apply the Security Context Constraint

The IBM Blockchain Platform requires specific security and access policies to be added to your project. The ibp-scc.yaml file
is provided here for you to copy and edit to define the security policies for your project. Before attempting this step, you should
be logged in to the oc CLI.
Copy and save the following security context constraint object to your local system as ibp-scc.yaml . Edit the file and replace
<PROJECT_NAME> with the name of your project.
allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
allowPrivilegeEscalation: true
allowPrivilegedContainer: true
allowedCapabilities:
- NET_BIND_SERVICE
- CHOWN
- DAC_OVERRIDE
- SETGID
- SETUID
- FOWNER
apiVersion: security.openshift.io/v1
defaultAddCapabilities: []
fsGroup:
type: RunAsAny
groups:
- system:serviceaccounts:<PROJECT_NAME>
kind: SecurityContextConstraints
metadata:
name: <PROJECT_NAME>
readOnlyRootFilesystem: false
requiredDropCapabilities: []
runAsUser:
type: RunAsAny
seLinuxContext:

type: RunAsAny
supplementalGroups:
type: RunAsAny
volumes:
- "*"
Run the following commands to add the file to your cluster and add the constraint to your project:
oc apply -f ibp-scc.yaml -n <PROJECT_NAME>

oc adm policy add-scc-to-user <PROJECT_NAME> system:serviceaccounts:<PROJECT_NAME>
Replace <PROJECT_NAME> with the name that you want to use for your IBM Blockchain Platform deployment project.
When the command is successful, you see a response that is similar to the following example:
securitycontextconstraints.security.openshift.io/blockchain-project created
scc "blockchain-project" added to: ["system:serviceaccounts:blockchain-project"]
Step two: Apply the image pull secrets

To apply the image pull secrets, go to the OpenShift Container Platform.
Note: The required global pull secret is automatically copied from the openshift-config namespace to the ibp
namespace. However, if the ibm-entitlement-keyimage pull secret is missing from the ibp namespace, manually
copy the secret to the ibp namespace and reference it in your YAML file, as described below.
1. In the left navigation, click Workloads > Secrets.

2. In the search box next to the Name drop down, type pull-secret.
3. From the listing page, select pull-secret.
4. Click the YAML tab.
5. In the YAML tab, you see the YAML code as follows. Right-click tocopy only the last two sets of codes. Those are the
secret data and the secret data handling type.
Figure 4. Pull-secret YAML Sample
6. After you copied the two sets of codes, go to the left navigation, clickSecrets. Then, use the Create drop down from the
upper right of the page to switch to From YAML.
7. Paste your two sets of codes under the existing YAML code.
8. Replace the existing YAML code by copying the following:
kind: Secret
apiVersion: v1
metadata:
name: regcred
namespace: <Your Blockchain Platform namespace>
1. Your complete set of pull-secret YAML code is now as follows:

kind: Secret
apiVersion: v1
metadata:
name: regcred
namespace: <Your IBM Blockchain Platform namespace>
data: <Your secret data here>
type: kubernetes.io/dockerconfigjson
1. Click Create to finish your setup.
Step three: Deploy the IBM Blockchain Platform console

There are four instances available listed under "Provided APIs":
Figure 1. Blockchain instances available in Red Hat Marketplace
IBP CA - (Advanced users) Deploys an instance of an IBM Blockchain Platform CA.

IBP Console - The IBM Blockchain Platform console UI, or "console", is an award-winning user interface for building your
blockchain network.
IBP Orderer - (Advanced users) Deploys an instance of an IBM Blockchain Platform ordering service.
IBP Peer - (Advanced users) Deploys an instance of an IBM Blockchain Platform peer.
Which instance should I choose?
All customers need to deploy an instance of the IBP Console to simplify the deployment and management of their blockchain
networks. The console itself is free. You are only billed for the blockchain nodes that you create by using the console.
Important: Note that this tutorial only includes instructions for deploying an instance of theIBP Console. Currently, you
cannot deploy Certificate Authorities (CAs), peers, and ordering nodes directly, you should use the console to deploy
those nodes instead.
Click Create Instance on the IBPConsole tile.
Figure 2. Click Create Instance on the IBP Console tile

Important: The YAML view shows a sample console specification of parameters that you need to customize. The spec is
abbreviated to only the required parameters. Be aware that some fields can show up differently based on your
configuration. Before you install the console, you should also review the Advanced deployment options in the next section
in case any of the other options are relevant to your configuration. For example, if you are deploying your console on a
multizone cluster, you need to configure that before you install the console.
apiVersion: ibp.com/v1beta1
kind: IBPConsole
metadata:
name: ibpconsole
namespace: example
labels:
app.kubernetes.io/name: "ibp"
app.kubernetes.io/instance: "ibp"
app.kubernetes.io/managed-by: "ibm-ibp"
spec:
email: <EMAIL>
password: <PASSWORD>
imagePullSecrets:
- regcred
registryURL: cp.icr.io/cp
license:
accept: <ACCEPT>
networkinfo:
domain: <DOMAIN>
storage:
console:
class: ''
size: 5Gi
serviceAccountName: ibm-blockchain
usetags: true
version: 2.5.3
Accept the IBM Blockchain Platform license by replacing <ACCEPT> with the text true.
Replace <EMAIL> with the email address that you want to use for the console administrator.
Replace <PASSWORD> with the password of your choice. This password becomes the default password for the console
administrator but they are required to change it the first time they log in.
Replace <DOMAIN> with the name of your cluster domain. You can find this value from your OpenShift web console URL.
Examine the URL for the current page. It is similar to: https://console-openshift-console.pa-0803-ocp43-
0defdaa0c51bd4a2dcb024eab4bf04a1-0000.us-
south.containers.appdomain.cloud/k8s/ns/pa0804/clusterserviceversions/ibm-
blockchain.v2.5.3/ibp.com~v1beta1~IBPConsole/~new. The value of the domain then would be pa-0803-ocp43-
0defdaa0c51bd4a2dcb024eab4bf04a1-0000.us-south.containers.appdomain.cloud, after you remove console-
openshift-console and /k8s/ns/pa0804/clusterserviceversions/ibm-
blockchain.v2.5.3/ibp.com~v1beta1~IBPConsole/~new.
You also need to make additional edits to the file depending on your choices in the deployment process. For example, if you
created a new storage class for your network, provide the storage class that you created to the class: field.
Tip: If you are running OpenShift on Azure, you also need to change the storage class from default to azure-
standard , unless you created your own storage class.
When you are satisfied with your edits to the specification, click Create.
Note: The console can take a few minutes to deploy.
After you create the console, you can verify that the console deployment is succeeded. See Step four: Verify the console
installation for instructions on verifying and accessing the console.

Advanced deployment options
Before you deploy the console, you can edit console specification to allocate more resources to your console or use zones for
high availability in a multizone cluster. To take advantage of these deployment options, you can use the console resource
definition with the resources: and clusterdata: sections added:
kind: IBPConsole
metadata:
name: ibpconsole
namespace: your-project
labels:
spec:
email: <EMAIL>
imagePullSecrets:
- regcred
license:
accept: <ACCEPT>
networkinfo:
domain: <DOMAIN>
storage:
console:
class: default
size: 5Gi
usetags: true
version: 2.5.3
clusterdata:
zones:
resources:
console:
requests:
cpu: 500m
memory: 1000Mi
limits:
cpu: 500m
memory: 1000Mi
configtxlator:
limits:
cpu: 25m
memory: 50Mi
requests:
cpu: 25m
memory: 50Mi
couchdb:
limits:
cpu: 500m
memory: 1000Mi
requests:
cpu: 500m
memory: 1000Mi
deployer:
limits:
cpu: 100m
memory: 200Mi
requests:
cpu: 100m
memory: 200Mi
You can use the resources: section to allocate more resources to your console. The values in the example file are the
default values allocated to each container. Allocating more resources to your console allows you to operate a larger

number of nodes or channels.
If you plan to use the console with a multizone Kubernetes cluster, you need to add the zones to the
clusterdata.zones: section of the file. When zones are provided to the deployment, you can select the zone that a
node is deployed to using the console or the APIs. As an example, if you are deploying to a cluster across the zones of
dal10, dal12, and dal13, you would add the zones to the file by using the format below.
clusterdata:
zones:
- dal10
- dal12
- dal13
When you finish editing the file, click Create.
Important: Unlike the resource allocation, you cannot add zones to a running network. If you have already deployed a
console and used it to create nodes on your cluster, you will lose your previous work. After the console restarts, you need
to deploy new nodes.
Use your own TLS Certificates (Optional)

The IBM Blockchain Platform console uses TLS certificates to secure the communication between the console and your
blockchain nodes and between the console and your browser. You have the option of creating your own TLS certificates and
providing them to the console by using a Kubernetes secret. If you skip this step, the console creates its own self-signed TLS
certificates during deployment.
Important: This step needs to be performed before the console is deployed.
You can use a Certificate Authority or tool to create the TLS certificates for the console. The TLS certificate needs to include the
hostname of the console and the proxy in the subject name or the alternative domain names. The console and proxy hostname
are in the following format:
Console hostname: <PROJECT_NAME>-ibpconsole-console.<DOMAIN>

Proxy hostname: <PROJECT_NAME>-ibpconsole-proxy.<DOMAIN>
Replace <PROJECT_NAME> with the name of your IBM Blockchain Platform deployment project.
Replace <DOMAIN> with the name of your cluster domain. You can find this value from your OpenShift web console URL.
Examine the URL for the current page. It is similar to: https://console-openshift-console.pa-0803-ocp43-
0defdaa0c51bd4a2dcb024eab4bf04a1-0000.us-
south.containers.appdomain.cloud/k8s/ns/pa0804/clusterserviceversions/ibm-
blockchain.v2.5.0/ibp.com~v1alpha2~IBPConsole/~new. The value of the domain then would be pa-0803-ocp43-
0defdaa0c51bd4a2dcb024eab4bf04a1-0000.us-south.containers.appdomain.cloud, after you remove console-
openshift-console and /k8s/ns/pa0804/clusterserviceversions/ibm-
blockchain.v2.5.0/ibp.com~v1alpha2~IBPConsole/~new.
Navigate to the TLS certificates that you plan to use on your local system. Name the TLS certificate tlscert.pem and the
corresponding private key tlskey.pem . Run the following command to create the Kubernetes secret and add it to your
OpenShift project. The TLS certificate and key need to be in PEM format.
kubectl create secret generic console-tls-secret --from-file=tls.crt=./tlscert.pem --from-

file=tls.key=./tlskey.pem -n <PROJECT_NAME>
After you create the secret, add the tlsSecretName field to the spec: section with one indent added, at the same level as the

resources: and clusterdata: sections of the advanced deployment options. You must provide the name of the TLS secret
that you created to the field. The following example deploys a console with the TLS certificate and key that is stored in a secret
named "console-tls-secret" :
kind: IBPConsole
metadata:
name: ibpconsole
namespace: your-project
labels:
spec:
email: <EMAIL>
imagePullSecrets:
- regcred
license:
accept: <ACCEPT>
networkinfo:
domain: <DOMAIN>
storage:
console:
class: default
size: 5Gi
usetags: true
version: 2.5.3
tlsSecretName: "console-tls-secret"
clusterdata:
zones:
- dal10
- dal12
- dal13
Step four: Verify the console installation

You can confirm that the console is up by running the following command, replacing <PROJECT_NAME> with the name of your
project:
kubectl get deployment -n <PROJECT_NAME>
If your console deployment is successful, you can see ibpconsole added to the deployment table, with a status of 4/4 . The
console takes a few minutes to deploy. You might need to rerun the command and wait for the table to be updated.
$ NAME READY STATUS RESTARTS AGE

ibp-operator-f58cc8585-hvsw7 1/1 Running 0 15m
ibpconsole-6f69477796-sxzm9 4/4 Running 0 4m
The console consists of four containers that are deployed inside a single pod:
optools: The console UI.

deployer: A tool that allows your console to communicate with your deployments.
configtxlator: A tool used by the console to read and create channel updates.
couchdb: An instance of CouchDB that stores the data from your console, including your authorization information.
If there is an issue with your deployment, you can view the logs from one of the containers inside the pod. First, run the following
command to get the name of the pod the console is deployed in:
kubectl get pods -n <PROJECT_NAME>

Then, use the following command to get the logs from one of the four containers:
kubectl logs -f <pod_name> <container_name> -n <PROJECT_NAME>
As an example, a command to get the logs from the UI container would look like the following example:
kubectl logs -f ibpconsole-55cf9db6cc-856nz optools -n blockchain-project
Step five: Log in to the console

Congratulations! You have deployed the IBM Blockchain Platform operator. The only thing left to do is to deploy the console user
interface (UI). First, click IBM Blockchain in the Installed Operators page.
You can find the URL of your blockchain console from the OpenShift cluster dashboard.
1. Click Workloads in the left navigation.

2. Click Config Maps.
3. You see several config maps, including <CONSOLE_NAME>, <CONSOLE_NAME>-console, and a <CONSOLE_NAME>-deployer.
Click the one that's just the <CONSOLE_NAME>, for example, ibpconsole.
4. In the Data section, you see the HOST_URL field. This is the URL of your console that you can now use to log in. It looks
similar to the following example:
$ https://blockchain-project-ibpconsole-console.xyz.abc.com
5. Paste your URL in your browser and login to the console.
In your browser, you can see the console login screen:
For the User ID, use the value you provided for the email: field in the console specification in step two.
For the Password, use the value you encoded for the password: field in the console specification in step two. This
password becomes the default password for the console that all new users use to log in to the console. After you log in for
the first time, you are asked to provide a new password that you can use to log in to the console.
Important: Ensure that you are not using the ESR version of Firefox. If you are, switch to another browser such as Chrome
and log in.
The administrator who provisions the console can grant access to other users and restrict the actions they can perform. For
more information, see Managing users from the console in the IBM Blockchain Platform 2.5.3 documentation.
Removing your deployment

If you want to delete the IBM Blockchain Platform operator or any instances you have deployed, the simplest way is through the
OpenShift UI.
Important: If you want to delete the operator, make sure to delete any instances associated with it first.
To delete an instance, navigate to the Operators tab and then click Installed Operators. From here, click IBM Blockchain and
then the All instances tab. Find the instance you that want to delete and click the settings button to the right of the instance.
Then, click Delete (the name of your instance).

To delete the operator, navigate back to the Installed Operators page and click the settings button to the right of the IBM
Blockchain Platform operator. Then, click Uninstall Operator.
Alternatively, you can use the CLI to switch to the OpenShift project that you created for your blockchain network:
$ ```
oc project <PROJECT_NAME>
```
And then remove any instances or the IBM Blockchain operator by using the OpenShift CLI. For example, this command would
delete the operator:
$ ```
kubectl delete deployment ibp-operator
```
Next steps
When you access your console, you can use the Nodes tab of your console UI to create CAs, peers, or an ordering service. See
the Build a network tutorial to get started with the console.
To learn how to manage the users that can access the console, view the logs of your console and your blockchain components,
see Administering your console.
Support
Support is provided for the paid version of the Red Hat Marketplace offering and support cases can be opened through the Red
Hat Marketplace support portal. Customers that use the trial version from Red Hat Marketplace, can refer to self-help resources
for assistance.
Create a project for your IBM Blockchain Platform deployment

Before you can deploy the operator, you need to create a project for your deployment of IBM Blockchain Platform. You can
create a new project by using the OpenShift web console or OpenShift CLI. The new project needs to be created by a cluster
administrator.
If you are using the CLI, create a new project by the following command:
oc new-project <PROJECT_NAME>
Replace <PROJECT_NAME> with the name that you want to use for your IBM Blockchain Platform deployment project.
Important: It is required that you create a new OpenShift project for each blockchain network that you deploy with the
IBM Blockchain Platform. For example, if you plan to create different networks for development, staging, and production,
then you need to create a unique project for each environment. Each project creates a new Kubernetes namespace. Using
a separate namespace provides each network with separate resources and allows you to set unique access policies for
each network. You need to follow these deployment instructions to deploy a separate operator and console for each
project.
When you create a new project, a new namespace is created with the same name as your project. You can verify that the
existence of the new namespace by using the oc get namespace command:
$ $ oc get namespace
NAME STATUS AGE
blockchain-project Active 2m

You can also use the CLI to find the available storage classes for your namespace. If you created a new storage class for your
deployment, that storage class must be visible in the output in the following command:
kubectl get storageclasses

About IBM Blockchain Platform for IBM Cloud
The IBM® Blockchain Platform for IBM Cloud is the next generation of IBM Blockchain Platform offerings, which gives you total
control over your deployments, certificates, and private keys. It includes the new IBM Blockchain Platform console, a user
interface that can simplify and accelerate the process of deploying components into a Kubernetes cluster on IBM Cloud
managed and controlled by you. For more information about deploying an Kubernetes cluster on IBM Cloud, see Kubernetes.
A key benefit of the platform is that IBM tests the open source code for security vulnerabilities daily and provides 24x7x365
support with SLAs appropriate for production environments.
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, or any Kubernetes v1.23 - v1.24 container platform on x86_64 hardware, see Getting started
with IBM Blockchain Platform 2.5.3.
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 container images, see Using the IBM Blockchain images.
Watch the following video for an introduction to blockchain and the IBM® Blockchain Platform:
View video: Key concepts video
Video script
Video transcript
What IBM Blockchain Platform offers

This latest release is tailored to experienced IBM Blockchain and Hyperledger Fabric users and lets them host and join IBM
Blockchain networks.
The IBM Blockchain Platform includes the following key features:
BUILD ---- Integrated developer experience
Deploy easily. Use Ansible Playbooks or the Red Hat Marketplace to deploy networks quicker than ever before.
Easily code your smart contracts in Node.js, Golang, Java, or JavaScript. Use the IBM Blockchain Platform Developer
Tools to easily develop smart contracts locally. Leverage SDK integration with the console, and learn from our rich
tutorials and samples.
Simplified DevOps allows you to move from development to test to production in a single environment by scaling up your
Kubernetes resources to add more components.
Up-to-date Fabric key features. Choose which version of Hyperledger Fabric you want to use when deploying peers or
ordering nodes. Leverage the latest features of Hyperledger Fabric v1.4.12 and v2.2.5:
Smart contract lifecycle
Raft ordering service
Private data collections that provide increased data privacy by ensuring that ledger data is shared to only
authorized peers via the gossip protocol.
Fabric Node OUs
Service discovery, allowing you to dynamically discover and update how your application interacts with your
network.
Channel access control lists that allow you additional control of the governance of your channels and smart
contracts.

OPERATE --- Total control of your deployments
Host or join a network. Deploy peers that are hosted in your cluster to multiple channels on multiple clouds, or invite
other organizations to join your consortium or channels while the organizations manage their nodes independently across
infrastructures.
Maintain complete control of your identities. Store and manage the keys that are used to administer your nodes.
Optionally, use a Hardware Security Module (HSM) to generate and store the private key of your nodes.
Run Anywhere. Thanks to the unified codebase of the IBM Blockchain Platform console, it is possible to run your
components on any environment supported by IBM Cloud and third-party public clouds.
Unified operation. The IBM Blockchain Platform console allows you to deploy and manage all of your organizations and
nodes in one console. You can also add or remove members from a blockchain consortium, create and join channels, and
deploy smart contracts from your console.
Dynamic signature collection that allows better control over collaborative governance over channel configurations.
Elimination of Docker-in-Docker for smart contracts allows smart contract pods to be run more securely, without peers
needing privileged access.
Manage access of the users who can administer or monitor your nodes.
Interact directly with your pods using the Kubernetes dashboard.
Direct access to the logs of your nodes from your IBM Kubernetes service. Use the IBM Log Analysis or any supported
third-party service to extract and analyze your logs.
Kubernetes service integration. Leverage services such as IBM Log Analysis for logging and Prometheus and IBM Cloud
Monitoring for monitoring. Leverage the built-in IBM Cloud services, such as IBM Cloud Kubernetes Service and OpenShift
dashboards, IBM Log Analysis, and IBM Cloud Identity and Access Management (IAM).
Upgrade the Fabric version of your nodes. Nodes running Fabric version 1.4.x can be upgraded to 2.x.
After which, the capabilities of your channels can also be increased to v2.0, allowing full access to the latest Fabric features like
the smart contract lifecycle.
GROW --- Scalability and flexibility
Choose your compute. You have the flexibility to decide the amount of CPU, memory, and storage you want to provision in
your Kubernetes cluster. For more information, see Allocating resources.
Scale up and down the resources in your Kubernetes cluster, paying for only what you need. For more information, see
Pricing.
Disaster recovery and multi-region high availability (HA). This option duplicates your Kubernetes deployment across
zones and regions, enabling high availability (HA) of your components and disaster recovery (DR).
Connect to other Fabric networks: Join IBM Blockchain Platform peers to any network running Hyperledger Fabric
components. Similarly, you can invite Fabric peers to join channels hosted on an ordering service deployed on the IBM
Blockchain Platform. Note that you will need to use Hyperledger Fabric APIs or the CLI.
This offering is intended for experienced Fabric users who want to build and manage their own networks.
Have questions and want to speak to an IBM Blockchain Platform expert? Schedule a consult now to learn more about how
blockchain can transform your business.
Supported IBM Cloud configuration

Reminder: If your IBM Blockchain Platform instance is linked to an IBM Cloud Kubernetes Service cluster that is no longer
supported, you must immediately upgrade it to a supported version listed in the table below. See Kubernetes version
information for Kubernetes version details. For the actual steps that are required, see Updating clusters, worker nodes, and
cluster components.
Kubernetes
v1.23 - v1.24

Orchestration
Service Kubernetes
OpenShift Container Platform on IBM Cloud 4.9, 4.10, 4.11
Infrastructure
Classic
Hardware
Security Tested with Cloud HSM
Module
(HSM)
VLAN
VLAN spanning must be enabled for multi-zone clusters.
Because private ingress is not supported, a cluster with only private VLANs is not supported as a
public internet connection is required for a connection between the IBM Blockchain cluster and the
customer Kubernetes cluster. A cluster with private and public VLANs configured is supported.
Storage
File
Block
Portworx
Object (For backups only, not intended for live storage)
Table 1. Supported IBM Cloud configuration
Fabric Component Support
Important: Support for Hyperledger Fabric v1.4 is now deprecated, and support for Fabric v1.4 will be removed from
IBM Blockchain Platform on March 31, 2023. Users should therefore upgrade to Fabric v2.2 as soon as possible. Your
applications may require changes as a result of upgrading to v2.2, so please plan for appropriate testing. Note that Fabric
v1.4 has not been supported by the Hyperledger community since April of 2021. In addition, Fabric v1.4 uses Golang
v1.14, which is no longer receiving security updates from the Golang community.
The following support levels are provided for Hyperledger Fabric v1.4.12 (Deprecated), v2.2.4, v2.2.5, and Fabric CA v1.5.0 and
v1.5.2.
Important: Using IBM Certified Fabric Images, Kubernetes Operator, and Certified Fabric Operations Console are
required for support and provide Hyperledger Fabric clients with a verified production setup, simplified management and
support, and verified security patches.
Fabric Component Support Level
IBM Certified Fabric images All Certified Fabric images include IBM fix support for supported Hyperledger
deployed using Kubernetes Operator Fabric versions.
and managed via the Certified Fabric
Operations Console image.
Supported Environments Recent Kubernetes and OpenShift versions on IBM Cloud, third-party Cloud or
local installations.

Hyperledger Fabric without IBM Not included in support - community support only
Certified Images, Kubernetes
Operator or Certified Fabric
Operations Console image.
Hyperledger Fabric Labs Support Fabric Operations Console via Certified Image and deployed by Kubernetes
Operator is supported.
Hyperledger Fabric Open Source Open source projects are not included in support, with the exception of Ansible.
Projects - IBM Blockchain GitHub All other open source projects are community support only.
Hyperledger Fabric SDK and CLI Basic connectivity diagnostics is supported. Code support and SDK API usage and
tuning are not included in support - community support only.
Hyperledger Fabric Chaincode Basic chaincode diagnostics is supported. Code support and tuning are not
included in support - community support only.
Deployment Architecture and Design Basic deployment and management of highly available peer, orderer, and
Certificate Authority nodes via the Console are supported. Detailed Deployment
Architecture and Design are not included in support - see deployment options for
more information.
Solution Architecture and Design Deploying and managing smart contracts via the Console are supported. Solution
Architecture and Design are not included in support.
Performance Tuning Resource allocation via the Console is supported. Detailed performance analysis
and tuning of the environment or application code are not included in support -
see the documentation on creating highly available applications and using
indexes with CouchDB.
Certificate Renewal Automatic and Manual Certificate renewal via the Certified Console image is
supported. The user is responsible for keeping track of identities and performing
manual certificate renewal. Using IBM Secrets Manager is recommended for
keeping track of identities and certificates.
Table 2. Fabric component support
Considerations
Before you deploy the console, ensure that you understand the following considerations:
You are responsible for the management of health monitoring, security, and logging of your Kubernetes cluster on IBM
Cloud. 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 on IBM Cloud. To monitor your
Kubernetes resources, we recommend using the IBM Cloud Monitoring tool in combination with your IBM Cloud
Kubernetes dashboard. If you need to increase storage capacity or performance 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 or in the console. They are only kept in the local storage of your browser. If you switch browsers,
you will have to import your created identities into that browser.
IBM Blockchain Platform is available in select regions. Refer to this topic on IBM Blockchain Platform locations for an
updated list.
The default storage that is pre-selected for you when you provision a Kubernetes cluster in IBM Cloud isGold. 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 on IBM Cloud, you must provision your
own storage. See Using Multizone (MZR) clusters with IBM Blockchain Platform for more details.
You can 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 cluster after 30 days and you cannot migrate any nodes or data from a free cluster
to a paid cluster. If you choose a paid Kubernetes cluster instead of the limited free cluster, you will incur charges for the
Kubernetes service to your IBM Cloud account.

Kubernetes clusters that are configured with private VLANs are not supported.
License and pricing

IBM Blockchain Platform for IBM Cloud introduces a new hourly pricing model based on virtual processor core (VPC) usage. The
simplified model is based on the amount of CPU (or VPC) that your IBM Blockchain Platform nodes consume on an hourly basis,
at a flat rate of $0.29 USD/VPC-hour, where 1 VPC = 1 CPU. See this topic on Pricing for more details.
Getting started
For information about how to deploy IBM Blockchain Platform for IBM Cloud, see Getting started with IBM Blockchain Platform
for IBM Cloud.
For more information about how to use the console to start deploying nodes and building consortium, see the Building your
network tutorial. This tutorial guides you through the process of using the console to create a sample network with three
organizations, one ordering organization, two peer organizations, and a channel with two peers joined to it. You can use this
sample network to for demos or proofs of concept or adjust and expand the steps in the tutorial to create your own custom
blockchain configuration.
Architecture reference
The following illustrations show the components of your blockchain network and how they interact with your cluster.
IBM Blockchain Platform on IBM Cloud Kubernetes Service Architecture
Figure 1. Architecture diagram of IBM Blockchain Platform on IBM Cloud Kubernetes Service
Notice how a single instance of the console, also known as Operational Tooling, is created for each IBM Blockchain Platform
Service Instance. When a peer, orderer or CA node is deployed by using the console, it is deployed into the Kubernetes Cluster
Service Instance.
IBM Description
Blockchain
Platform
Kubernetes
Cluster
Operational Also known as the "console", this is your central user interface for operating all of your blockchain
Tooling components. With this console you can create CA, peer, and ordering nodes, create channels and use smart
contracts. The console is deployed in an IBM-owned cluster. There is no charge for this tooling or the
Kubernetes cluster on IBM Cloud where it runs.
Kubernetes Description
cluster on
IBM Cloud
instance
Operator A Kubernetes operator that is used to deploy the console.
Ingress A Kubernetes object that allows access to the cluster resources from outside the cluster.

Proxy The IBM Blockchain Platform proxy is responsible for routing traffic to the correct peer, CA and ordering
nodes by using host header routing.
Peers, CAs, These are the nodes that are created. These nodes can also be imported from other consoles. Because
ordering the private keys are never stored by IBM, every peer and ordering node includes a gRPC web proxy that
nodes allows the console to communicate with each node by using the keys in the wallet.
RBAC Role based access control. The IBM Blockchain Platform configures Kubernetes RBAC in the cluster
which is required to manage blockchain components in the cluster.
IBM Blockchain Platform on Red Hat OpenShift Architecture
Figure 2. Architecture diagram of IBM Blockchain Platform on Red Hat OpenShift in IBM Cloud
A single instance of the console, also known as Operational Tooling, is created for each IBM Blockchain Platform service
instance. When a peer, ordering node, or CA is deployed by using the console, it is deployed into the Red Hat OpenShift Cluster
Service Instance.
IBM Description
Blockchain
Platform Red
Hat
OpenShift
Cluster
Operational Also known as the console, this is your central user interface for operating all of your blockchain
Tooling components. With this console you can now create CA, peer, and ordering nodes, create channels and use
smart contracts. The console is deployed in an IBM-owned cluster. There is no charge for this tooling or
the Kubernetes cluster on IBM Cloud where it runs.
Table 4. Components that reside in the IBM Blockchain Platform Kubernetes Cluster
OpenShift Description
cluster
Operator A Kubernetes operator that is used to deploy the console.
Routes An OpenShift route is a way to expose a service by giving it an externally reachable hostname.
Proxy The IBM Blockchain Platform proxy is responsible for routing traffic to the correct peer, CA and ordering nodes
by using host header routing.
Peers, These are the nodes that are created. Note: these nodes could also be imported from other Kubernetes
CAs, Cluster Service Instances. Because the keys are never stored by IBM, every peer and ordering node includes a
Ordering gRPC web proxy that allows the console to communicate with each node by using the keys in the wallet.
nodes
RBAC Role based access control. The IBM Blockchain Platform configures OpenShift RBAC in the cluster which is
required to manage blockchain components in the cluster.
Integrating with IBM Cloud and other third-party services

IBM Blockchain Platform can leverage a suite of services provided in the IBM Cloud catalog to enable users more visibility into
their network or to integrate with other services.

Figure 2.IBM Cloud Integrations
Access control
Securely authenticate users and control access to all cloud resources using IBM Cloud Identity and Access Management
(IAM).
Monitoring
Use IBM Cloud Activity Tracker service to troubleshoot logs in real-time, diagnose issues, and identify problems in your
Kubernetes cluster on IBM Cloud.
Use IBM Cloud Monitoring to monitor the activity and the health of services and applications in the Kubernetes cluster on
IBM Cloud.
See this tutorial on how to Analyze logs and monitor application health with IBM Log Analysis and IBM Cloud Monitoring.
The IBM Blockchain Platform peers and orderers are automatically configured to expose a /metrics endpoint that
Prometheus can use to scrape a wide variety of blockchain metric data. Read more about using Prometheus in IBM Cloud.
Storage
Utilize IBM Cloud File or Block storage when blockchain nodes are provisioned. See the topic on Persistent storage
considerations to learn more about how blockchain integrates with IBM Cloud storage options.
Set up Portworx to manage local persistent storage across your containerized databases, or share data between pods
across multiple zones.
For more information about available IBM Cloud services and other third-party integrations, see this list of Supported IBM Cloud
and third-party integrations.
Compliance
For a list of the current security certifications that IBM Blockchain Platform adheres to, see the Software Compatibility Reports.
Getting support
For more information about how to get support on IBM Blockchain Platform for IBM Cloud, as well as free blockchain developer
resources and support forums that you can use to troubleshoot problems, see Getting support.

What's new
This page announces major changes to IBM Blockchain Platform.
May 03, 2022

IBM Blockchain Platform is now available and includes the following enhancements and changes:
Hyperledger Fabric v2.4.3 support.

Fabric Gateway peer service support.
Kubernetes Operator will now perform a rolling restart of Hyperledger Fabric pods when updating configuration to help
avoid downtime.
Hyperledger Fabric v1.4 support was deprecated from IBM Blockchain Platform Software and SaaS on March 31, 2022.
Support will be removed on March 31, 2023.
Updated Supported Platforms, including support for OpenShift Container Platform (OCP) 4.10.

Blockchain component overview
The components and structure of the IBM® Blockchain Platform are based on the underlying infrastructure and tools of
Hyperledger Fabric, an open source permissioned blockchain solution to which IBM is a major contributor. Networks based on
Fabric include several standard components that can be deployed in a number of configurations to support a wide variety of use
cases.
For a more comprehensive overview of Fabric networks and the interrelation of the components that comprise it, see this
document on the structure of a blockchain network from the Fabric community documentation, which shows how a network can
be started and matured.
For the purposes of this overview, we focus just on certificate authorities (CAs), orderers, peers, smart contracts, and
applications. As you can see from the Build a network tutorial, this sequence is not arbitrary; it reflects the proper order in which
components in a network based on Fabric are deployed.
Peers
At a conceptual level, a blockchain network is comprised mainly of organizations (as organizations decide on how a network is
structured, as well as owning nodes and managing identities). At a physical level, however, a blockchain network is comprised
primarily of peer nodes that are owned and administered by organizations. Peers are the fundamental elements of the network
because they host ledgers and smart contracts (which are contained in "chaincode"), and are therefore where transactions are
executed and validated.
More accurately, the peer hosts instances of the ledger, and instances of smart contracts. Because smart contracts and ledgers
are used to encapsulate the shared processes and shared information in a network, these aspects of a peer make them a good
starting point to understand what a Fabric network does.
To learn more about peers specifically, check out Peers from the Fabric community documentation.
The IBM Blockchain Platform console allows you to create peers, join them to channels, create anchor peers, install smart
contracts, and seamlessly upgrade your peers.
Certificate Authorities (CAs)

You can think of a blockchain network as a series of managed interactions between nodes to serve a defined business use case.
For these interactions to be verifiable (to ensure, in other words, who is who) requires identities and a system of permissions that
can be checked during each interaction. You can think of the kind of identity that is needed as being similar to a credit card in
that it identifies someone within a particular context. Credit cards identify an individual in terms of banking transactions, while
Fabric identities allow users to be identified in a blockchain context.
In Hyperledger Fabric, as well as the IBM Blockchain Platform, this component is the Certificate Authority (CA), which creates
identities in the form of x509 certificates as well defining of an organization through the creation of a Membership Services
Provider (MSP), which defines the permissions of identities at a component and channel level. These identities can include
attributes about them, for example, by linking them to a particular organization or organizational unit (OU).
An organization MSP, for example, has an MSP subfolder calledadmins. Any user whose certificate is inside that admin folder is
an admin of the organization. Because this MSP defines the organization, it is listed in the configuration on every channel of
which the organization is a member. As a result, whenever an admin of the organization tries to perform an action, the signing
certificate of the admin (which is attached to all of its interactions) is checked against the certificates listed in the MSP. Does the
certificate match the one listed in the channel configuration? If it does, the other organizations will validate it and the action can
be performed. If not, the request to execute the transaction is rejected.

IBM Blockchain Platform CAs are based on the Hyperledger Fabric CA, though it is possible to use another CA if it uses a PKI
based on x.509 certificates. Because non-Fabric CAs are not configured to create properly formatted MSPs, users who want to
use this kind of CA must create the MSP for themselves.
For more information about how certificate authorities are used to establish identity and membership, see Hyperledger Fabric
documentation on identity and on membership.
Ordering services
Many distributed blockchains, such as Ethereum and Bitcoin, feature systems in which any node can participate in the process
where transactions are ordered and bundled into blocks. Because of this fact, these systems rely on probabilistic consensus
algorithms that eventually guarantee ledger consistency to a high degree of probability, but are still vulnerable to divergent
ledgers (also known as a ledger “fork”), where different participants in the network have a different view of the accepted order of
transactions.
Hyperledger Fabric works differently. It features a kind of a node that relies on deterministic consensus algorithms that is called
an “ordering node” or an "orderer", that does this transaction ordering. The collection of ordering nodes form the "ordering
service".
In addition to promoting finality, separating the endorsement of smart contract execution (which happens at the peers) from
ordering gives Fabric advantages in performance and scalability, eliminating bottlenecks that can occur when execution and
ordering are performed by the same nodes.
The ordering service performs one other key function: In networks that use a system channel the orderers maintain the
"consortium", the list of organizations that can create and join application channels. Because some aspects of the configuration
of application channels are inherited by default from the system channel (certain capability levels, for example), it is the job of
ordering service admins to establish these defaults. Note however that the ordering service organization can add additional
administrating organizations to the system channel.
Orderers that do not use a system channel have REST APIs, called Channel Participation APIs. These APIs replace the
application channel management features that the system channel provided.
The IBM Blockchain Platform uses an implementation of the Raft protocol, in which a leader node is dynamically elected among
the ordering nodes in a channel (this collection of nodes is known as the “consenter set”), and that leader replicates messages
to the follower nodes. Because the system can sustain the loss of nodes, including leader nodes, as long as there is a majority of
ordering nodes (what’s known as a “quorum”) remaining, Raft is said to be “crash fault tolerant” (CFT). In the IBM Blockchain
Platform, users have the ability to select a single node ordering service or a five node ordering service, though it is possible to
add or remove nodes from an ordering service and from channels later on. Similarly, it is possible for either one organization or
multiple organizations to manage the ordering service and contribute nodes.
For more information about the ordering service, see The Ordering Service.
Channels
A channel is a mechanism that provides a private layer of communication, allowing subsets of network members to create a
separate ledger for their transactions. Channels are not just private in the sense that network members who are not a part of the
channel are unable see the transactions, they are also secret in the sense that unless a network member is a part of the channel,
they will not even know that the channel exists.
Multiple channels can be created between members, thus supporting one of the many mechanisms to implement privacy. As
discussed in the section on peers, data in a blockchain network is stored on peers in a ledger. Each channel has a separate
ledger that holds the transactions (which include configuration transactions) for that channel.

The IBM Blockchain Platform allows channels to be easily created and managed. Channel configuration updates allow the
members of a channel to edit channel parameters to fit their use case. For example, more members can be added to a channel,
or the capabilities of a channel can be changed. Because changes to a channel must be approved by channel members, the IBM
Blockchain Platform provides a mechanism for the collection of necessary signatures.
For more information about channels and how to use them, see the Hyperledger Fabric documentation.
Smart contracts
Before businesses can transact with each other, a common understanding about rules and processes must be reached and
defined. Taken together, these contracts lay out the "business model" that governs all of the interactions between business
partners.
The same need exists in blockchain networks. The industry term for these business models on blockchain networks is "smart
contracts". Fabric networks contain these contracts in a larger structure that is known as "chaincode", which includes not just
the business logic but the underlying infrastructure that validates the identities of the users that attempt to invoke the smart
contract.
Where contracts in the business world are signed and filed with law firms, smart contracts are installed on peers and deployed
on a channel.
For more information about smart contracts, see Smart contracts.
Applications
Client applications in a Fabric-based network like IBM Blockchain Platform leverage underlying infrastructures such as APIs,
SDKs, and smart contracts to allow client interactions (invokes and queries) at a higher level of abstraction.
For a look at how applications interact with a network based on Fabric, check out the Developing Applications topic in the
Hyperledger Fabric documentation. You can also view the creating applications topic to learn how to connect your applications
to IBM Blockchain Platform.
An example network
Figure 1 depicts an example of a deployed blockchain network that consists of four organizations, Org A, Org B, Org C, and Org D.
Each organization has their own Certificate Authority that is responsible for distributing cryptographic identity material. There is
also an ordering service with five Raft nodes that defines policies and network participants. Channel X includes all four
organizations, but Channel Y is restricted to Org C and Org D. Lastly, client applications in possession of a properly signed x509
certificate can send calls to their associated peers on the network.

Org A Org C
Fabric SDK
Fabric SDK
Channel X
Certificate Authority Certificate Authority Client App 3
Client App 1
Ledger X Ledger X
Ordering Service Org
Ledger Y
Org A Peer Org C Peer
Ledger
Certificate Authority
Channel Y
Ledger X Ledger Y
Org B Ordering Service Nodes Org D
Fabric SDK Fabric SDK

Certificate Authority Certificate Authority
Client App 2 Ledger X

Client App 4
Ledger X
Ledger Y
Org B Peer Org D Peer
Figure 1. An example blockchain network with four members that leverage channels to isolate data

Pricing
Pricing for IBM Blockchain Platform for IBM Cloud
This guide helps you understand the pricing model for IBM® Blockchain Platform for IBM Cloud, and how much you will pay
when you develop and grow your blockchain network of peers, ordering nodes, and Certificate Authorities components, which
are based on Hyperledger Fabric v1.4.12 and v2.2.5.
Pricing model
IBM Blockchain Platform introduces a new hourly pricing model that is based on virtual processor core (VPC) allocation. This
simplified model is based on the amount of CPU (or VPC) that your IBM Blockchain Platform nodes are allocated on an hourly
basis, at a flat rate of $0.29 USD/VPC-hour.
Note: A VPC is a unit of measurement that is used to determine the licensing cost of IBM products. It is based on the
number of virtual cores (vCPUs) that are available to the product. A vCPU is a virtual core that is assigned to a virtual
machine or a physical processor core. For IBM Blockchain Platform cost estimation purposes, 1 VPC = 1 CPU = 1 vCPU =
1 Core. The term "VPC" is also used to refer to a type of infrastructure on IBM Cloud and is unrelated to this topic.
For a total cost estimate, remember that your blockchain network consists of an Kubernetes cluster on IBM Cloud that contains
IBM Blockchain Platform components and uses storage of your choice. Your Kubernetes cluster on IBM Cloud and the storage
that you choose incur separate charges. You will not be charged for the cluster that the Operational Tooling instance, also known
as the console, is running on. See the Architecture reference topic for an illustration. More details on how to calculate charges
are described below.
Benefits of the new pricing model

No membership fees: Freedom from membership fees means that you can invest directly in your blockchain components.
Estimation clarity: A simple hourly pricing model makes cost estimation clear and easy by using the cost estimator tool
that is available in the IBM Cloud dashboard.
No minimum fee required: Pay for only what you use, no minimum VPC hourly package is required, which makes it very
inexpensive to get started.
Scalability of compute: You have the option to scale your compute up during peak usage periods or down to a minute
fraction of capacity for when the compute is not needed to minimize expense.
In summary, these features remove the complexity of accounting for membership limitations or purchasing compute ahead of
your needs.
Find out how to preview the platform free for 30 days

You can 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.
Limitations of the free preview
Performance will be limited by throughput, storage, and functionality. Read more about the limitations of free clusters.
IBM Cloud will delete your Kubernetes cluster after 30 days.
Only one blockchain console can be connected to a free cluster at a time.
You cannot migrate any nodes or data from a free cluster to a paid cluster.
The following capabilities are only available on a paid cluster:
Customizing resource allocation for a node during or after deployment.

Using a Hardware Security Module (HSM) to secure the private key for a node.

Configuring a Certificate Authority (CA) for high availability by using a PostgreSQL database and replica sets.
Selecting a specific Kubernetes zone when deploying a node.
Overriding node configuration during or after deployment by using the console or APIs.
Adding or removing ordering nodes to an ordering service. The free offering only supports a single node Raft ordering
service.
How to preview IBM Blockchain Platform for free
1. Get an IBM Cloud Account.

2. Upgrade your IBM Cloud Account to "Pay-as-you-go" by adding in a credit card. You will not be charged.
3. Launch IBM Blockchain Platform in the IBM Cloud Catalog.
4. Under Select a pricing plan, ensure that the Standard plan is selected and then click Create.
5. On the Welcome and pre-requisites panel that opens, click I have a Cluster (Skip to Link a cluster).
6. In the Select an IBM Kubernetes Service cluster drop-down list, select your free cluster. Note: If your free cluster is not
listed, ensure sure you are not using the ESR version of Firefox. If you are, switch to another browser such as Chrome and
retry.
7. Click Deploy to cluster.
8. When the platform is ready, you can click Launch the IBM Blockchain Platform to open the blockchain console UI and get
started. Watch the video to learn how to Deploy a peer on the IBM Blockchain Platform, or try out the getting started
tutorial Build a network.
After 30 days, your Kubernetes cluster is deleted along with all of your blockchain nodes and data.
Key elements of cost

Because your blockchain network consists of an Kubernetes cluster on IBM Cloud that contains IBM Blockchain Platform
components and uses storage of your choice, each of the following elements forms your total cost.
Figure 1. Elements of pricing
IBM Blockchain Platform: Based on a flat rate of $0.29 USD/VPC-hour. This fee represents the charge for your blockchain
component VPC allocation in your Kubernetes cluster.
IBM Cloud Kubernetes Service: While you can link your IBM Blockchain Platform service instance to either an IBM Cloud
Kubernetes service cluster or an OpenShift cluster, this pricing model is based on the usage of an IBM Cloud Kubernetes
service cluster. The IBM Cloud Kubernetes service uses a tiered pricing model that is visible in IBM Cloud when you
provision your paid cluster. This includes the charges for your compute, that is, CPU and memory. IBM Cloud Kubernetes
Services are priced on a tiered model that is based on the number of hours of usage per month. Therefore, when you
examine pricing plans, consider that 24x7 usage is equivalent to 720 hours per month. Refer to the table on the
Kubernetes Service Catalog page for more details on cluster pricing. Customers who are interested in pricing OpenShift
clusters can review Red Hat OpenShift on IBM Cloud Pricing.
Storage: Choose the storage plan that works for your needs. See Understanding Kubernetes storage basics to learn more
about your storage class options and how much they cost. The IBM Blockchain Platform nodes use the default storage
class for the cluster. When you provision a Kubernetes cluster in IBM Cloud, it is preconfigured with Gold File storage as
the persistent storage plug-in.
Advanced features: Options that are available for Production networks for increased security, disaster recovery, and
health monitoring of the nodes. Costs vary depending on the options you choose.
Tip: When you allocate VPCs (or CPU) to a blockchain node, the node consumes CPUs from your Kubernetes cluster
allocation. Therefore the size of the Kubernetes cluster that is required directly depends on the size and quantity of the
blockchain nodes that you deploy.
Pricing examples
The following table provides two examples of pricing with default resource allocations unless otherwise noted. Both examples
assume an IBM Cloud Kubernetes service cluster and the default CouchDB database is used as the peer database. It also

assumes peers are deployed with Fabric v2.x images instead of Fabric v1.4 images.
The Test network scenario is suitable for getting started with your first use case with IBM Blockchain and testing smart
contracts.
The Join a network scenario includes two peers, and a Certificate Authority (CA) that is required for organization
membership.
These peers can join a production IBM Blockchain Platform network that is hosted elsewhere.
Nodes can always be dialed back to a minimal utilization state (0.001 CPU) when they are not in use to lower costs.
Because this scenario could be used for a production environment:
The default compute resources have been doubled to provide greater capacity.
The Silver storage class is chosen for faster performance.
Pricing options** (1 VPC = 1 CPU Test Network Join a Network

= 1 vCPU)
CPU allocation 1.25 vCPU 2.9 vCPU

Includes: Includes:
- 1 peer (0.7 vCPU) - 2 peers (for HA)
- 2 CAs (0.1 vCPU x 2) (2x default compute = 2 x 0.7 x 2)
- 1 ordering node (0.35 vCPU) - 1 CA (0.1)
Hourly cost: IBM Blockchain $0.46 USD $0.81 USD

Platform (1.25 vCPU x $0.29 USD/VPC-hr) (2.9 vCPUx $0.29 USD/VPC-hr )
Hourly cost: IBM Cloud $0.29 USD $0.29 USD

Kubernetes cluster (Compute: 4 x 16 lowest tier; 1 worker (Compute: 4 x 16 lowest tier; 1 worker
node; 1 zone) node; 1 zone)
Hourly cost: Storage $0.06 USD $0.09 USD

340GB 420GB
Bronze Silver
2 IOPS/GB 4 IOPS/GB
Total hourly cost $0.71 USD $1.19 USD
Table 1. Pricing examples for a test network and joining a network
** 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 is 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.
Note: Your actual costs will vary depending on additional factors such as transaction rate, the number of channels you
require, the payload size on the transactions, and the maximum number of concurrent transactions. The pricing examples
above are based on an IBM Cloud Kubernetes single-zone cluster only. If you chose a multi-zone cluster, there are extra
fees for the additional zones and the required multi-zone load balancer. IBM Cloud IP allocation charges are not included
and considered negligible.
There is no limit to the number of service instances that you can provision and associate to a single Kubernetes cluster. But you
need to ensure that adequate resources are available by monitoring the CPU, memory, and storage usage to avoid disruption of
service. The IBM Blockchain Platform nodes do not have to be in their own cluster. You can have other IBM Cloud services
running in the same cluster that your blockchain components are running in, but again you need to ensure that you have
adequate compute and storage to address all the requirements of all service instances.
Interested in more pricing examples? See the Reference topic on Detailed pricing scenarios for additional configurations and
prices.

Ready to get started? Check out Getting started with IBM Blockchain Platform to see the options.
Default resource allocations

The values in the following table are useful to estimate the hourly cost of your custom network based on CPU, compute, and
storage. These minimum recommended values are sufficient for getting started. As you monitor your network usage, you might
find that your actual resource requirements and costs will vary depending on your use case and your security and availability
needs.

(GB)
CA 0.1 0.2 20
Operator 0.1 0.2 0
Console 1.2 2.4 10
Table 2. Recommended resources for nodes on IBM Blockchain Platform for IBM Cloud
Billing
Your IBM Blockchain Platform billing and invoices are based on the CPU and memory allocation for each node. When you are
done with your network and want to avoid any further charges, you need to delete your nodes from the console and then delete
your blockchain service instance from IBM Cloud. Storage that was provisioned for the node is automatically deleted when the
node is deleted.
IBM Cloud and IBM Blockchain Platform charges

If IBM Cloud has your credit card on file, you will be sent a link to view your invoice. You can also view it from your IBM Cloud
Dashboard by navigating to Manage > Billing and Usage > Invoices.
1. Click the Download icon next to the invoice you want to view.
2. You will have the option to download your invoice in "PDF invoice" or "EXCEL invoice" format.
PDF invoice Select this format when limited detail is required. This format includes the line-item "Platform Services
Containers" that includes your IBM Cloud Kubernetes and Storage costs (as well as other container costs). The line
item "Platform Services Other Services" aggregates your blockchain cost with other service costs.
EXCEL invoice Select this format when you need more insight into your Kubernetes containers, storage instances,
and blockchain cost. Navigate to the Detailed Billing sheet in the downloaded invoice workbook to understand how
those specific line items break down, and see details of the specific containers/storage instances you got charged
for. The Blockchain Platform cost is visible under the Description line item "Platform Service Plan Feature Usage:

Blockchain Platform Standard" . For example, a Detailed Billing tab would look similar to the following:
Figure 2. Kubernetes cluster charges
Note: The pie-chart visible on the Usage tab of the IBM Cloud Dashboard will not align with the invoices since it applies to
a different billing period.
Storage usage
If you are using IBM Cloud File storage, the costs are assessed monthly, so an estimate of storage costs is not visible until the
end of the month. However, the storage that you provisioned throughout the month is listed as line items in the Usage tile under
Sales > Orders. Look in the Items column for a description of the storage that was dynamically provisioned when you deployed
a peer, CA, or ordering node.
Optimizing the cost of your nodes

One of the key benefits of the IBM Blockchain Platform pricing model is the ability to dial back or delete resources when they are
not needed.
Switch your nodes to Minimum Utilization State

CPU on individual nodes can be scaled down to 0.001 CPU to completely minimize charges. Taking these actions renders
the node non-functional. When the compute is needed later, you can use the reallocation option in the IBM Blockchain
Platform console to scale up to what is required. For more information about how resources can be reallocated, see
Reallocating resources.
Delete unused peer and deploy a new one when needed. Because the ledger is stored on the ordering node, when you
deploy a new peer and join a channel, the peer receives a copy of the distributed ledger. The drawback to this approach is
that you need to generate new certificates and join the peer to the channels again.
Important: It is not recommended to ever delete a CA node because the data on it can never be recovered. Likewise,
if you have only a single ordering node, you should never delete it.
Monitor and adjust your resource allocation based on your needs. When you monitor your resource usage over time, you
might decide that you can scale down the resources that are allocated to a node while still ensuring adequate
performance. When you follow instructions for reallocating resources in the console, the effects on total VPC for the node
are updated and can be used to estimate revised monthly costs.
Detailed pricing scenarios

This topic includes additional detailed pricing and sizing scenarios to help you learn more about the potential costs of various
IBM® Blockchain Platform for IBM Cloud network configurations.
Target audience: This advanced topic is designed for architects and system administrators who are responsible for planning and
sizing the cost of an IBM Blockchain Platform network on IBM Cloud.
Important: The costs that are provided in this topic are based on the usage ofIBM Cloud Kubernetes service clusters.
The costs are guidelines and do not represent actual costs. They represent a starting point for estimates of costs that
would be incurred in environments with a similar configuration. Actual costs can vary by geography. The prices reflected
here are based on the resources required by Fabric v1.4 peer images and actual prices as of October 16, 2019. It is
possible the prices can change. The performance of your configuration depends on your smart contracts and the queries

you are running. To determine your actual costs, it is important that you test the configuration to verify that the
performance satisfies your requirements.
Note: If you need to first learn more about the basic elements that factor into the cost a blockchain network, review the
topic on Pricing for IBM Blockchain Platform for IBM Cloud.
Scenario comparisons
The following table includes configuration and cost information for three types of environments:
Functional Test/Demo
Pilot
Production or Pre-Production
Click a tab to view the details for a configuration. Each tab contains two options:
Cost to host This column represents the cost to host a blockchain network, therefore the configuration includes an
ordering service, CAs, and peers.
Cost to join This column represents the cost to join an existing blockchain network by contributing peers or an new
organization with peers to the network. This configuration includes only CA and peer nodes.
For example, consider the scenario where a group oforganizations want to transact on a blockchain network. The network might
include buyers, suppliers, distributors, and banks. If you are hosting a network, you could host the ordering service and some
organizations such as the buyers, and suppliers. Or, if you are a distributor, you might prefer to simply join the existing network.
The tables below includes the costs for each type of scenario.
All storage costs are calculated based on IBM Cloud Bronze File Storage costs.
For IBM Blockchain Platform cost estimation purposes, 1 VPC = 1 CPU = 1 vCPU = 1 Core.
Assumptions Cost to Host Cost to Join

Goal: A simple test or demo Configurations include: Total estimated cost Total estimated cost
environment. Larger peers for more per month: $606 USD per month: $368 USD
robust integration testing.
Includes: Includes:
You can join the peers to multiple CouchDB
channels to better simulate a real Single node Raft 1 CA
environment or put them all in one File Storage (Bronze) ordering service
account. 0.1 vCPU/0.2GB
Not included: HA, Backup, 0.35 vCPU/0.7GB RAM/20 GB Storage
This network would typically include HSM, Log Analysis, RAM/100GB Storage
2-3 organizations. Monitoring, Dedicated 1 Peer
hardware/HW 2 CAs 1.1 vCPU/2.8 GB
RAM/100 GB Storage
2 x (0.1 vCPU/0.2GB
RAM/20 GB Storage) Peer container:
0.2 vCPU/1GB
1 Peer RAM/50GB
1.1 vCPU/2.8 GB Storage
RAM/100 GB Storage CouchDB
container: 0.2
Peer container: vCPU/0.4GB
0.2 vCPU/1GB RAM/50GB
RAM/50GB Storage
Storage
Smart contract
Couch container: 0.5
container: 0.2 vCPU/1GB
vCPU/0.4GB RAM/0GB
RAM/50GB Storage
Storage
Logging/gRPC
Smart contract Web container:
container: 0.5 0.2 vCPU/0.4GB
vCPU/1GB RAM/0GB
RAM/0GB Storage
Storage
Logging/gRPC
Web container:
0.2 vCPU/0.4GB
RAM/0GB
Storage
Total Resources vCPU: 1.65 vCPU: 1.2

RAM: 3.9GB RAM: 3.0GB
Storage: 240GB Storage: 120GB
Approximate Total Cost IBP: 1.65vCPU x IBP: 1.2vCPU x .29/hr

(per hour) .29/hr = $0.48 USD = $0.35 USD
IKS*: $0.31 USD IKS*: $0.13 USD
Storage: $0.05 USD Storage: $0.03 USD
Total: 0.84 USD/hr Total: 0.51 USD/hr
*IKS 4x16 single node *IKS 2x4 single node
cluster with IP cluster with IP
allocation (Shared allocation (Shared
hardware) hardware)
Approximate Total Cost IBP: $346 USD IBP: $252 USD

(per month) IKS: $224 USD IKS: $94 USD
Storage:$36 USD Storage:$22 USD
Total Base Cost: $606 Total Base Cost: $368
USD USD
Table 1. Functional Test/Demo Pricing Scenarios

Goal: A relatively large test environment for Configuration Total estimated Total estimated
evaluating an overall solution for eventual includes: cost per month: cost per month:
production. $3,737 USD $1,816 USD
CouchDB
Includes multiple organizations and slightly Includes: Includes:
increased resources for HA/Performance, but File Storage
not meant for production. (Bronze)
5 node Raft 1 CA
HA protection from node failure. If one node HA via node ordering service
goes down, for maintenance for example, the redundancy 0.1 vCPU/0.2GB
network can still be fully operational. If zero 5 x (1 vCPU/1GB RAM/20 GB Storage
downtime is not important for this Pilot Optional: Backup RAM/500GB
environment, you could use a smaller Tests, Storage) 2 Peers
configuration, such as a single zone, 4 node 4 x PostgreSQL
16 cluster. Database, 2 CAs 2 x (2.2 vCPU/4.4GB
File Storage (Silver), RAM/ 750 GB
This network would typically include 3-5 HSM, 2 x (0.1 vCPU/0.2GB Storage)
organizations. Log RAM/20 GB Storage)
Analysis/Monitoring, Peer
Dedicated hardware 2 Peers container: 0.5
vCPU/1GB
2 x (2.2 vCPU/4.4GB RAM/250GB
RAM/ 750 GB Storage
Storage) CouchDB
container: 0.5
Peer vCPU/1GB
container: 0.5 RAM/500GB
vCPU/1GB Storage
RAM/250GB
Storage Smart
contract
CouchDB container: 1
container: 0.5 vCPU/2GB
vCPU/1GB RAM/0GB
RAM/500GB Storage
Storage
Smart Logging/gRPC
contract Web
container: 1 container: 0.2
vCPU/2GB vCPU/0.4GB
RAM/0GB RAM/0GB
Storage Storage
Logging/gRPC
Web
container: 0.2
vCPU/0.4GB
RAM/0GB
Storage

RAM: 14.2GB RAM: 9GB
Approximate Total Cost IBP: 9.6vCPU x IBP: 4.5vCPU x

(per hour) .29/hr = $2.79 USD .29/hr = $1.31 USD
IKS*: $1.59 USD IKS*: $0.90 USD
Storage (Bronze): Storage (Bronze):
$0.81 USD $0.31 USD
Total: $5.19 USD/hr Total: 2.52 USD/hr
* IKS 1 zone x 3 * IKS 1 zone x 3
node - 8 x 32 cluster node - 4 x 16 cluster
with IP allocation with IP allocation
(Shared hardware) (Shared hardware)
Approximate Total Cost IBP: $2,008 USD IBP: $944 USD

(per month) IKS: $1,145 USD IKS: $648 USD
Storage Storage
(Bronze):$584 USD (Bronze):$224 USD
Total Base Cost: Total Base Cost:
$3,737 USD $1,816 USD

Optional upgrades HA CA HA CA
(PostgreSQL): +$40 (PostgreSQL): +$40
USD/month USD/month
HSM (when HSM (when
available): +$1,250 available): +$1,250
USD/month USD/month
Storage Storage
(Silver):+$224 (Silver):+$105
USD/month USD/month
IBM Log Analysis: IBM Log Analysis:
$1.50/GB/Month (7 $1.50/GB/Month (7
day search) day search)
IBM Cloud IBM Cloud
Monitoring: Monitoring:
0.035/hour/node 0.035/hour/node
(up to 20 (up to 20
containers) containers)
Table 1. Pilot Pricing Scenarios
Goal: Production environment. Pre- Configuration Total estimated cost Total estimated cost
production should match production as includes: per month: $5,778 per month: $3,467
closely as possible in terms of size, USD USD
performance, HA, and capability. CouchDB
Includes: Includes:
This network would typically include 5 or File Storage (Silver)
more organizations. 5 node Raft ordering 2 CAs
HA with multi-zone service
region ( MZR) 2 x (.1 vCPU/2 GB RAM)
5 x (1 vCPU/1GB + (20 GB shared
Backup (Backup RAM/500GB Storage) storage)
test in pre-prod,
Run backups 4 CAs 2 Peers
regularly in Prod)
4 x (0.1 vCPU/0.2GB 2 x (3.7 vCPU/8.4GB
HA CA PostgreSQL RAM) + (2 x 20 GB RAM/ 750 GB Storage)
Database (2 CAs shared storage)
with 2 replica sets) Peer container: 1
2 Peers vCPU/2GB
Optional: RAM/250GB
HSM, 2 x (3.7 vCPU/8.4GB Storage
Log RAM/ 750 GB Storage) CouchDB
Analysis/Monitoring, container: 1
Dedicated hardware Peer container: vCPU/2GB
1 vCPU/2GB RAM/500GB
RAM/250GB Storage
Storage
Smart contract
CouchDB container: 1.5
container: 1 vCPU/4GB
vCPU/2GB RAM/0GB Storage
RAM/500GB
Storage Logging/gRPC
Web container:
Smart contract 0.2 vCPU/0.4GB
container: 1.5 RAM/0GB Storage
vCPU/4GB
RAM/0GB
Storage
Logging/gRPC
Web container:
0.2 vCPU/0.4GB
RAM/0GB
Storage

RAM: 22.6GB RAM: 17.2GB

Approximate Total Cost IBP: 12.8vCPU x .29/hr IBP: 7.6vCPU x .29/hr =
(per hour) = $3.71 USD $2.20 USD
IKS*: $2.74 USD IKS*: $1.85 USD
Storage (Silver): $1.21 Storage (Silver): $0.46
USD USD
Total: $7.67 USD/hr Total: $4.51 USD/hr
* IKS 3 zone x 3 node - * IKS 3 zones x 2 node -
4x16 cluster with IP 4 x16 cluster with IP
allocation and load allocation and load
balancer (Shared balancer (Shared
hardware) hardware)
Approximate Total Cost HA CA PostgreSQL IBP: $2,671 USD IBP: $1,584 USD
(per month) config: IKS: $1,972 USD IKS: $1,332 USD
5 GB disk, 1 GB Storage (Silver):$871 Storage(Silver):$331
RAM, 10GB for USD USD
backups, 1 vCPU HA CA (PostGreSql):
$40 USD HA CA (PostGreSql):
Storage costs for $40 USD
backups:$224 USD Storage costs for
backups:$180 USD
Total Base Cost:
$5,778 USD Total Base Cost:
$3,467 USD
IBM Log Analysis:
$1.50/GB/Month (7 day IBM Log Analysis:
search) $1.50/GB/Month (7 day
search)
IBM Cloud Monitoring:
0.035/hour/node (up to IBM Cloud Monitoring:
20 containers) 0.035/hour/node (up to
20 containers)
Optional upgrades HSM (when available): HSM (when available):

+$1,250 USD/month +$1,250 USD/month
Dedicated IKS Dedicated IKS
hardware: +$1,848 hardware: +$1,236
USD/month USD/month
Table 1. Pre-Production/Production Pricing Scenarios

Security
IBM® Blockchain Platform provides a scalable, highly reliable platform that helps customers deploy applications and data
quickly and securely. This document provides information about securing your IBM Blockchain Platform service instance, where
the blockchain console runs, and best practices for securing the linked Kubernetes cluster where the blockchain nodes are
deployed.
Security on the IBM Blockchain Platform console

Audience: Tasks in this section are typically performed by blockchain network operators.
Configuration of an IBM Blockchain Platform network includes deploying the blockchain console and then linking it to either a
new or existing customer Kubernetes cluster. The blockchain console can then be used to create blockchain nodes that reside in
the customer Kubernetes cluster.
Considerations include:
IAM (Identity and Access Management)

Ports
Key management
Membership service providers (MSPs)
Access control lists (ACLs)
API authentication

Identity and access management allows the owner of a console to control which users can access the console and their
privileges within it. Identity and access management on IBM Cloud is controlled by using the IAM service. Every user that
accesses the blockchain console must have an IBMid account and be assigned an access policy in the IAM service. This policy
determines what actions the user can perform within the console. Blockchain-specific permissions (for example, which users
can create components) are based on the IAM roles that are mapped to blockchain permissions in this Role to permissions
mapping table.
When the IBM Blockchain Platform console is provisioned, the email address of the IBM Cloud account owner is set as the
console administrator, known in IAM as the Manager role. All new access requests will be sent to this user. This console
administrator can then grant other IBMid users access to the console by using the IAM UI. For more information about IAM on
IBM Cloud, see What is IAM. For the steps required to add new users, see Adding and removing users from the console.
Ports
If you are using a client application to send requests to the console, either via the blockchain APIs or the Fabric SDKs, the
associated HTTPS console port needs to be exposed in your firewall. In IBM Cloud use the default port 443 .
Key management
The IBM Blockchain Platform network is based on trusted identities. Customers use the Certificate Authorities (CAs) in the
console to generate the identities and associated certificates that are required by all members to transact on the network. The
generated public and private keys are ECDSA with Curve P256 . These keys are stored in the browser when they are added to
the member's blockchain wallet so that the console can use them to manage blockchain components. However, it is
recommended that customers export these keys and import them into their own key management system in case they clear
their browser cache or switch browsers. Customers are responsible for the storage, backup, and disaster recovery of all keys that
they export.

Because these public and private key pairs are essential to how the IBM Blockchain Platform functions,key management is a
critical aspect of security. If a private key is compromised or lost, hostile actors might be able to access your data and
functionality. Although you use the IBM Blockchain Platform console to generate the certificates and private keys, they are not
permanently stored by the browser or the cloud database. Public and private keys are temporarily stored in the browser and
added to the member's wallet so that the console can use the private key to digitally sign transactions. Customers are ultimately
responsible for exporting the keys and managing their storage, backup, and disaster recovery.
If a private key is lost and cannot be recovered, you will need to generate a new private key by registering and enrolling a new
identity with your Certificate Authority. You should also then remove and replace your signCert in any components or
organizations where you had used the lost or corrupted identity. See Updating an organization MSP definition for detailed steps.
In order to secure private keys in a production environment, the IBM Blockchain Platform includes the option to configure a
Hardware Security Module (HSM) to generate and store the private keys for a node. An HSM is an optional hardware appliance
that performs cryptographic operations and ensures that the cryptographic keys never leave the HSM. You are responsible for
configuring an HSM device that implements the PKCS #11 standard. PKCS #11 is a cryptographic standard for secure
operations, generation, and storage of keys. You will also need to configure a PKCS #11 proxy to communicate with your HSM.
The platform supports ECDSA Sign and Verify cryptographic controls and EC Key generation. When an HSM is implemented for a
node, the private key for the node is not stored in the browser wallet. Rather, the private key is accessed from the HSM via the
proxy. When you register other node admin or client application identities with a CA by using the console, their private keys are
not stored inside the HSM because they need the private key to transact on the network. For instructions on how to use HSM
with the IBM Blockchain Platform, see Configuring a node to use a Hardware Security Module (HSM).
You also have the option to bring your own certificates from your own non-IBM Blockchain Platform CA when you create a peer
node or ordering service. If you use your own certificates, you will need to manually build the peer or ordering service MSP
definition file that includes those certificates and import the file into the console Organizations tab. See Using certificates from
an external CA with your peer or ordering node for the steps required.
Membership Service Providers (MSPs)

Whereas Certificate Authorities generate the certificates that represent identities, turning these identities into roles in the IBM
Blockchain Platform is done through the creation of Membership Service Providers (MSPs) in the console. These MSPs, which
structurally are comprised of folders containing certificates, are used to represent organizations on the network. Every
organization will have one and only one MSP and will always contain at least one admincert that identifies an administrator of the
organization. When an MSP is associated with a peer, for example, it denotes that the peer belongs to that organization. Later on
in the flow for creating a peer (or any node), this same administrator identity can be used to serve as the administrator of the
peer as well. In order to perform some actions on a node, an administrator role is required. For example, to be able to install a
smart contract on a peer, your public key must exist in the admincerts folder of the peer's organization MSP, which therefore
makes you an administrator of the peer organization.
MSPs also identify the root CA that generated the certificates for the organization and any other roles beyond administrator that
are associated with the organization (for example, members of a sub-organizational group), as well as setting the basis for
defining access privileges in the context of a network and channel (e.g., channel admins, readers, writers).
MSP folders for organization members are based on a Fabric defined structure and are used by Fabric components. For more
information about Fabric MSPs and their structure, see the Membership and Membership Service Provider Structure topics in
the Hyperledger Fabric documentation. The Fabric CA establishes this structure by creating the following folders inside the MSP
definition:
MSP folder name Description

cacerts Contains the certificate of the root CA of your network.
intermediatecerts These are the certificates of any intermediate CAs in your chain of trust (leading back to a
root CA or CAs). Because intermediate CAs are currently not supported by the IBM
Blockchain Platform, this field will be blank.
keystore Contains the private key that was generated alongside your public key. This key is used to
generate signatures by creating a cryptographic hash that can be verified using the public
key known to other users. This key is never shared, and you are responsible for securing and
managing it. If this key becomes compromised, it can be used to impersonate your identity,
making it crucial to keep this key safe.
signCerts Contains the public key that was generated alongside your private key. It is also known as a
"signing certificate" because it is used to verify signatures generated by other users.
Many Fabric components

contain additional
information inside their
MSP folder. For example, a
peer, includes the following
folders:
admincerts Contains the admin certificates for this organization or component.
tls Contains the TLS certs that you store for communicating with other network components.
Table 1. MSP folders
Note that organization MSPs are stored in browser storage and must be exported to a local file system and secured by the
customer.

Hyperledger Fabric allows for finer grained control over user access to specified resources through the use of access control lists
(ACLs). ACLs allow access to a channel resource to be restricted to an organization and a role within that organization. The
available set of ACLs are from the underlying Fabric architecture and are selected during channel creation or update. Note that
access control lists are restrictive, rather than additive. If access to a resource is specified to an organization, it means that only
that organization will have access to the resource. For example, if the default access to a particular resource is the Readers of
all organizations, and that access is changed to the Admin of Org1, then only the Admin of Org1 will have access to the resource.
Because access to certain resources is fundamental to the smooth operation of a channel, it is highly recommended to make
access control decisions carefully. If you decide to limit access to a resource, make sure that the access to that resource is
added, as needed, for each organization.
You can use the blockchain console to select which ACLs to apply to resources on a channel. See this information under
Creating a channel for instructions on how to configure access control for a channel.
API authentication
In order to use the blockchain APIs to create and manage network components, your application needs to be able to
authenticate and connect to your network. See this topic on API Authentication on IBM Cloud
Best practices for security on the customer Kubernetes cluster

Audience: Tasks in this section are typically performed by Kubernetes infrastructure managers.
The IBM Blockchain Platform console allows you to deploy and manage nodes on a Kubernetes cluster that you operate. The

previous section addressed the security of the console. The following sections detail the best practices you can use to secure
your Kubernetes cluster and the nodes of your network:
Kubernetes cluster security

Network security
Internet Ports
Cluster and Operating System (OS)
Keys and cluster access information
Storage
Data privacy
GDPR

The best place to start is to learn about the security features of the underlying Kubernetes infrastructure. The open source
documentation provides a review of recommended practices for securing a Kubernetes cluster.
If you are using IBM Cloud, you can review the topic on Security for the IBM Cloud Kubernetes Service or Red Hat OpenShift on
IBM Cloud.
Network security
IBM Cloud provides the underlying network, including the networks and routers, over which customers’ VLAN resides. The
customer configures their servers and uses gateways and firewalls to route traffic between servers to protect workloads from
network threats. Protecting your cloud network by using firewalls and intrusion prevention system devices is imperative for
protecting your cloud-based workloads.
Firewall configuration
Kubernetes clusters should be secured by a firewall to protect the network from unauthorized access from internet traffic. By
default IBM Cloud Kubernetes service clusters are preconfigured with a Calico network plug-in that secures the public network
interface of every worker node in the cluster. By configuring Kubernetes and Calico network policies you can easily control the
inbound and outbound network traffic. For more information, see Controlling traffic with network policies. In addition, you can
also configure Edge worker nodes on your IBM Cloud Kubernetes service clusters to restrict the worker nodes that are exposed
to the public internet. See Restricting network traffic to edge worker nodes to learn more. If your configuration includes a
network firewall, there are ports that need to be exposed to allow network traffic through. The following section describes how
to find the ports that can be exposed and what they are for.
Internet Ports
IBM Blockchain Platform exposes certain ports associated with each node type that are used by client applications, for example,
when sending transactions to peers or the ordering service. If you have configured a firewall, you will need to expose these ports
in your network for the transactions to reach their destination and for the nodes to be able to respond to the requests. IBM
Blockchain Platform supports the HTTPS IP Security protocol.
If your IBM Blockchain Platform instance is linked to an OpenShift cluster in IBM Cloud, port 443 needs to be exposed.
If your IBM Blockchain Platform instance is linked to an IBM Cloud Kubernetes service cluster, use the following table to
identify the ports that need to be exposed:
Port Number Description

CA ports
Fabric CA 7054 Port 7054 is exposed from the CA container. This is exposed all the way to the
customer application via the service.
Peer ports
Peer gRPC API 7051 This is the port used by the clients to communicate with the peer.
Smart contract 7052 This is the port used by the smart contract containers to communicate with the
containers peer.
Peer Operations 9443 This port is used to get to the health check endpoint and to the metrics endpoint of
the peer.
gRPC Web proxy 7443 This port is used by the UI to communicate with the peer via gRPC web APIs.
Ordering service
ports
Orderer gRPC API 7050 This is the port used by the clients to communicate with the orderer.
Orderer 8443 This port is used to get to the health check endpoint and to the metrics endpoint of
Operations the Orderer.
gRPC Web proxy 7443 This port is used by the UI to communicate with the orderer via gRPC web APIs.
Table 2. Ports on IBM Cloud
Cluster and Operating System security

Sensitive data: Cluster configuration data is stored in the etcd component of your Kubernetes master. Data in etcd is
stored on the local disk of the Kubernetes master and is backed up to IBM Cloud Object Storage. Data is encrypted during
transit to IBM Cloud Object Storage.
UBI Linux: The Fabric Docker images use Red Hat UBI images, which is a smaller, lighter, and more secure version of
Linux.

Type Description Storage Access
Customer In order for the service components After generation, these Accessed only by the service
Kubernetes to access and manage the secrets never leave the component code and only in
cluster components that are deployed into IBM Kubernetes cluster response to customer requests to
access this cluster, the service components where the service deploy or manage components via
information generate a Kubernetes secret for components are running the blockchain console.
cluster access. Each Kubernetes and are deleted whenever Developers of the service do not
secret is tied to that specific a customer deletes the have access to the information in
customer cluster. associated cluster. the secrets.
Table 3. Types of keys and information used to access the customer Kubernetes cluster

Organizations in a blockchain network are represented by MSP definitions. You can use the blockchain console to add a new
organization to the network by creating a new MSP definition in the Organizations tab. If you are the admin of an ordering
service, you can use the console to add that organization MSP to a consortium using the Ordering service tab. Finally, if you are
an administrator of a channel, you can add that organization to an existing channel so the organization can transact on the

network using the Channels tab (this task might require the signature of other organizations). See the topic on Join the
consortium hosted by the ordering service for detailed steps.
Storage
When the blockchain console deploys a node, storage is dynamically provisioned from the default storageclass for that node
from persistent storage. You have the option of encrypting the persistent volume but there may be some performance
implications with encryption to consider.
Important: Customers are responsible for encrypting their own storage and the encryption must occur before any
blockchain components are deployed to the cluster.
The default persistent storage type is File storage, also known as Endurance storage. For more information about encryption on
all of the IBM Cloud storage options:
IBM Cloud File storage Provider managed encryption-at-rest

Portworx encrypting volumes
IBM Cloud data encryption and key management
Data privacy
When you have data privacy requirements, Private Data collections provide a way to further isolate specific data from the rest of
the channel members. The combination of the use of channels and private data offer various solutions for achieving Data
Residency.
GDPR
In order to be GDPR compliant, it is recommended that you store PII data off chain.
Hyperledger Fabric Security

Because IBM Blockchain Platform is based on Hyperledger Fabric, you can leverage the secure features included in a Fabric
network.
TLS v1.2 communications TLS is embedded in the trust model of Hyperledger Fabric. By default, server-side TLS is
enabled for all communications using TLS certificates. TLS is used to encrypt the communication between your nodes and
between your nodes and your applications. TLS prevents man-in-the-middle and session hijacking attacks. All IBM
Blockchain Platform components use TLS to communicate with each other.
Transaction integrity: Fabric uses the cryptographic ECDSA standard to guarantee transaction integrity. With ECDSA, the
transaction originator, such as a client application, signs their message by using their private key, and the recipient, such
as a peer, uses the originator’s public key to verify the authenticity of the message. If a transaction is tampered with on its
way to the recipient, the signature verification fails.
Channels: While Fabric channels are a powerful mechanism for partitioning and isolating data, they also provide the
primary foundation for data privacy. Only members of the same channel can access the data of this channel. To ensure
channel security, the channel configuration update policy is configured to define the number of channel operators who
need to agree on the channel update request before a channel can be updated. Therefore, a clear process must exist for
defining the organizations that are allowed to join and update channel.
Ledger data: Implicit in the blockchain permissioned network is the notion that an agreed upon policy of multiple
endorsers is required to sign (approve) a transaction before it can be committed to the ledger. Before any information can

be added to the ledger, a clear and well-established process for defining the ledger information must exist. Data on the
ledger is immutable.
Smart contracts: All smart contracts should be reviewed by channel members before they are installed and executed on
peers in their organization. Likewise, all updates to smart contract should be reviewed before the updates are applied to a
peer. See this topic on Upgrading a smart contract for the steps that are required.
HSM integration: After you have configured an HSM for your environment, you have the option of configuring your nodes
to use the HSM to generate and store private keys. See Configuring a CA, peer, or ordering node to use the HSMfor more
information.
Enable network policy

Enable network policy will automatically install when the console is created. In the operator deployment specification, the
operator needs to add an environment variable IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY and set its value to true .
$ kubectl edit deploy ibp-operator -n <offering-namespace>
In the environment section under spec.containers , add the following:
$ - name: IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY
value:"true"
When the option above is enabled, the operator will install two network policies during the console installation. These network
policies are meant to give basic defensive security mechanism, and opens only the ports that the offering uses. This by no
means is a policy that can replace a firewall. The policies applied provide ingress security, as blockchain network may require to
call npm, gradle, maven servers to get chaincode modules as well as to communicate with the orderers/peers/applications
running outside the cluster on internet we do not provide egress policies.
The following two policies are applied:
1. Deny-all-ingress.
This policy denies all ingress ( ingress: [] ) network traffic to the pods ( podSelector: {} ) in the namespace it applies to.
This ensure only the needed traffics go through.
$ kind: NetworkPolicy
apiVersion: networking.k8s.io/v1
metadata:
name: networkpolicy-denyall
namespace: <>
labels:
type: "ibp-console"
app.kubernetes.io/instance: "ibp-console"
app.kubernetes.io/managed-by: "ibp-operator"
release: "operator"
helm.sh/chart: "ibp"
spec:
podSelector: {}
ingress: []
1. Ingress.
This ingress network policy applies to network traffic coming from anywhere (from: []) . It applies to all pods that labels
app.kubernetes.io/name: "ibp" which are all the offering related pods. This policy only opens the ports that are required
for the blockchain components and the available management console from outside for them to connect to each other.

$ kind: NetworkPolicy
apiVersion: networking.k8s.io/v1
metadata:
name: networkpolicy-ingress
labels:
type: "ibp-console"
app.kubernetes.io/instance: "ibp-console"
app.kubernetes.io/managed-by: "ibp-operator"
release: "operator"
helm.sh/chart: "ibp"
spec:
ingress:
- from: [] # everywhere
ports:
- port: 7051 # peer-api
protocol: TCP
- port: 9443 # peer-operations / ca-operations
protocol: TCP
- port: 7443 # peer-grpcweb / orderer-grpcweb
protocol: TCP
- port: 7052
protocol: TCP # peer-chaincode
- port: 3000 # optools
protocol: TCP
- port: 7050 # orderer-grpc
protocol: TCP
- port: 8443 # orderer-operations
protocol: TCP
- port: 22222 # fileserver #check install/invoke chaincode
protocol: TCP
- port: 11111 # grpc #check install/invoke chaincode
protocol: TCP
- port: 7054 # ca
protocol: TCP
podSelector:
matchLabels:
policyTypes:
- Ingress

High availability
High availability (HA)
Use the built-in Kubernetes features along with IBM® Blockchain Platform component deployment strategies to make your
blockchain networks more highly available and protect your network from downtime when a failure occurs in your cluster.
Target audience: This topic is designed for architects and system administrators who are responsible for planning and
configuring IBM Blockchain on IBM Cloud .
High availability is a core discipline in an IT infrastructure to keep your apps up and running, even after a partial or full site
failure. The main purpose of high availability is to eliminate potential points of failures in an IT infrastructure. For example, you
can prepare for the failure of one system by adding redundancy and setting up failover mechanisms.
You can achieve high availability on different levels in your IT infrastructure and within different layers of your cluster. The level
of availability that is right for you depends on several factors, such as your business requirements, the Service Level Agreements
that you have with your organizations, and the cost of redundancy.
Before proceeding, we recommend that you learn more about HA on Kubernetes by reviewing High availability for the IBM Cloud
Kubernetes service or OpenShift cluster.
Then, you can use this topic for details on blockchain-specific HA guidance along with the recommendations from the platform-
specific topic above.
Overview of potential points of failure in IBM Blockchain Platform

The IBM Blockchain Platform architecture is designed to ensure reliability, low latency processing, and a maximum uptime of the
service. However, failures can happen. IBM Blockchain Platform provides several approaches to add more availability to your
cluster by adding redundancy and anti-affinity policies. Anti-affinity ensures that blockchain components of the same type and
organization are deployed across different worker nodes. By adding redundancy across your blockchain network, you can avoid
failures or downtime.
To achieve maximum high availability, it is recommended that you build redundancy by provisioning peers and orderers in
Kubernetes clusters in multiple regions. When the components are spread across regions and the blockchain ledger is
distributed across those components, a failure in any single region will not impact processing of transactions. CAs are less
critical for daily transaction processing. After all the users have been registered and enrolled with the CA, it is no longer required
until the next time those services are required.
Peer considerations
HA for peers means always having redundant peers, that is at least two peers available for each organization on the same
channel to process requests from client applications. Multiple peers can be deployed to a single worker node, or spread across
worker nodes, zones (if you are using IBM Cloud), or even regions. Whenever you deploy multiple peers and join them to the
same channel, the peers act as HA pairs because the channel and the data are automatically synchronized across all peers in
the channel. By design, a blockchain network is meant to have multiple organizations that transact on the same channels.
Therefore, the common deployment model is that for any given channel, there are redundant peers for each organization spread
across several organization account clusters that are all synchronizing data between each other. Each organization can have a
peer in their own cluster in any region.
For even more robust HA coverage, you can stand up multiple clusters in multiple regions and deploy peers in all of them.
However, if high performance is desired, care must be taken when distributing peers to ensure the latency and bandwidth
between them is sufficient to achieve your performance targets.

Anchor peers on a channel facilitate cross-organization communication that is required for private data, gossip, and service
discovery to work. If only one anchor peer exists on a channel, and that peer becomes unavailable, the organizations are no
longer connected and the cross-organization gossip is no longer possible. Therefore, when you create redundant peers for an
organization, be sure to add redundant anchor peers on the channel as well.
Finally, your peer redundancy strategy needs to take into account your smart contract endorsement policies to ensure that you
always have enough peers available to satisfy the endorsement policy requirements. For example, if an endorsement policy
requires a specific number of endorsements, your peer HA strategy needs to ensure that there are always that number of peers
available. Alternatively, if the endorsement policy requires a MAJORITY of peers to endorse the transactions, then you need to
ensure that a majority of the peers are always available in order for transactions to continue to be processed.
Ordering service considerations

IBM Blockchain Platform is built upon Hyperledger Fabric v1.4.12 and v2.2.5 that includes the Raft ordering service. Raft is a
crash fault tolerant (CFT) ordering service based on an implementation of Raft protocol. By design, Raft ordering nodes
automatically synchronize data between them using Raft-based consensus. In IBM Blockchain Platform, an organization
network operator can choose to stand up either a single node Raft-based orderer, with no HA, or five orderers in a single region
or across multiple regions that are automatically configured for HA via Raft.
Certificate Authority (CA) considerations

Because CA nodes process user registration and enrollment requests for your blockchain network, they are typically not high-
throughput nodes. However, if HA is important for your CA strategy, it is possible to configure your nodes for maximum
availability. Kubernetes includes built in HA by immediately restarting the pod if the CA becomes unavailable. However, if you
cannot tolerate any downtime for your CA, you have the option to configure replica sets for your CA. A replica set is a
Kubernetes mechanism that is used to guarantee the availability of the pod. The use of replica sets ensures that multiple
replicas of the pod are running at all times. If one of the CA replicas becomes unavailable, Kubernetes immediately switches to
another CA replica, therefore there is no downtime waiting for a CA to restart.
HA Checklist
The following table contains a list of options to consider as you plan for increasing degrees of HA.
Single Single cluster with multiple Multizone Multiple clusters across

node nodes regions
Redundant peers
Redundant anchors peers on a

channel
Anti-affinity (peers)
Multi-zone (peers)
Raft ordering service
Ordering nodes + anti-affinity + anti-

affinity
CA replica sets

Anti-affinity (CA replica sets)
Development or Test
environment
Production environment
Table 1. Comparison of deployment scenarios to increase your network HA
** The default configuration for a Standard Kubernetes cluster on IBM Cloud is a 4 CPU x 16 GB RAM cluster that includes three
zones with three worker nodes each. You can scale up or down, by selecting a smaller or larger configuration, according to your
needs.
Tip: The IBM Blockchain Platform deployer attempts to spread peers, ordering nodes, and CA replica sets across
different worker nodes but cannot guarantee that it will happen due to resource limitations. You can also use the IBM
Blockchain Platform APIs or the blockchain console to deploy peers or ordering nodes to specific zones in order to ensure
that they are resilient to a zone failure. For more information see Multizone HA.
Potential points of failure

IBM Blockchain Platform offers several approaches to add more availability to your network by adding redundancy and using
anti-affinity policies. Review the following diagrams to learn more about potential points of failure and how to eliminate them.
You can select a model based on your application criticality, service levels, and costs. As general rule, you can implement the
redundancy to meet your service levels. All of these scenarios must be weighed against the cost of implementing greater
resiliency.
Single region HA
2
Region 1
Single Cluster
1 + anti-affinity
Region 1
Worker Pool
Worker Node 1
Single Cluster Peer1 Org1CACA
1 1 Peers
Ordering Node 1
Peers
R1 (Raft)
R2
Worker Pool
Worker Node
Peer1 Org1 CA 1 Peers Ordering Node 1
CA 1
Peers Worker Node 2
R1 (Raft)
R2
Peer2 Org1CACA
1 2 Peers Ordering Node 3
Peer2 Org1 CA 2 Peers Ordering Node 2 Peers
CA 1 R1 (Raft)
Peers R2
R1 (Raft)
R2
Ordering Node 2
Ordering Node 3
(Raft)
(Raft)
Ordering Node 4
Worker Node 3
(Raft)
Ordering Node 4
Ordering Node 5
(Raft)
(Raft)
Ordering Node 5
(Raft)
Increasing blockchain high availability
Figure 1. Blockchain HA single region options
1. Component failure.

Single-zone cluster:
Every time that you deploy a blockchain component, such as a peer, ordering node, or CA, a new pod is created for the
component in a worker node. Containers and pods are, by design, short-lived and can fail unexpectedly. For example, a
container or pod might crash if an error occurs in your component. So, to make your node highly available, you must
ensure that you have enough instances of it to handle the workload plus extra instances in case of a failure.
Peers How many peers are required? In a production scenario, the recommendation is to deploy three peers from the same
organization to each channel. This configuration allows one peer to go down (for example, during a maintenance cycle)
and still maintain two highly available peers. Therefore, to compensate for a peer failure, and for the most basic level of
HA, you can achieve peer redundancy by simply deploying three peers per organization on a channel on your worker node.
Note that you need to ensure that you have adequate resources available on your node to support these components.
Ordering service As mentioned above, the HA ordering service is based on Raft, and contains five ordering nodes by default.
Because the system can sustain the loss of nodes, including leader nodes, as long as there is a majority of ordering nodes
(what’s known as a “quorum”) remaining, Raft is said to be “crash fault tolerant” (CFT). In other words, if you have five
nodes in a channel, you can lose two nodes (leaving three remaining nodes). When you deploy an ordering service from
the console, choose the five node service for HA.
CA You can configure replica sets, which are represented as shaded CA boxes in the diagram above, for your CA. Replica
sets guarantee that if the CA node goes down, the CA replica immediately begins processing requests. You must provision
an instance of a PostgreSQL database if you plan to use CA replica sets. See these instructions for more information about
how to configure CA replica sets.
This scenario uses redundant peers, ordering nodes, and CAs on a single worker node, which protects against component
failure, but cannot protect from node failure. Therefore, it is only suitable for development and testing purposes.
2. Worker node failure.
Single-zone cluster with multiple worker nodes and anti-affinity:
A worker node is a VM that runs on a physical hardware. Worker node failures include hardware outages, such as power,
cooling, or networking, and issues on the VM itself. You can account for a worker node failure by setting up multiple
worker nodes when you provision your cluster. When blockchain components are distributed across multiple worker
nodes, you are protected from a worker node failure.
Peers The IBM Blockchain Platform deployer anti-affinity policy distributes redundant peers, that is peers from the same
organization, across the worker nodes in their cluster.
Ordering service Whenever you deploy a Raft ordering service, the five ordering nodes are automatically distributed across
the worker nodes in your cluster, using the anti-affinity policy and based on resource availability on the nodes.
CAs Like peers and ordering nodes, if replica sets are chosen for a CA, an anti-affinity policy automatically distributes the CA
replica sets across worker nodes in the cluster, based on resource availability.
This scenario uses redundant peers, ordering nodes, and CA replica sets, across multiple worker nodes in a single cluster or
zone, which protects against node failure, but cannot protect from a cluster or zone failure. Therefore, it is not
recommended for production.
Multizone HA

3
Region 1
Zone 1 Zone 2 Zone 3
Multizone Cluster
+ anti-affinity (across worker nodes)
WorkerPool
Worker Node 1 Worker Node 1 Worker Node 1
Worker Node 1 Worker Node 1
Peer 1 Org 1 CA 1 Peers Peer 3 Org 1 CA 1 Peers Ordering Node 4
R1 R2 (Rafts)

Peer 2 Org 1 Ordering Node 2 CA 2 Peers Peer 4 Org 1 CA 2 Peers
(Rafts) R1 R2

Ordering Node 1 Ordering Node 3 Ordering Node 5
(Raft) (Raft) (Raft)
Figure 2. Blockchain HA single zone options
Zone failure.
Multizone clusters with multiple worker nodes and anti-affinity:
Think of a zone as a data center. A zone failure affects all physical compute hosts and NFS storage. Failures include power,
cooling, networking, or storage outages, and natural disasters, like flooding, earthquakes, and hurricanes. To protect against a
zone failure, you must have clusters in at least two different zones that are load balanced by an external load balancer. By
default when you deploy a Kubernetes cluster in IBM Cloud, the cluster is configured with multi-zone support, including three
zones, although you can choose two zones.
A single zone is sufficient for a development and test environment if you can tolerate a zone outage. Therefore, to leverage the
HA benefits of multiple zones, when you provision your cluster, ensure that multiple zones are selected. Two zones are better
than one, but three are recommended for HA to increase the likelihood that the two additional zones can absorb the workload of
any single zone failure. When redundant peers from the same organization and channel, and ordering nodes, are spread across
multiple zones, a failure in any one zone should not affect the ability of the network to process transactions because the
workload will shift to the blockchain nodes in the other zones.
You can use the IBM Blockchain Platform console to specify the zone where a CA, peer, or ordering node is created. When you
deploy a CA, peer, or ordering service (or a single ordering node), check the Advanced deployment option that is labeled
Deployment zone selection to see the list of zones that is currently configured for your Kubernetes cluster.
If you're deploying a CA, peer, or ordering service, you have the option to select the zone from the list of zones available to your
cluster or to let your Kubernetes cluster decide for you by leaving the default selected. For a five node ordering service, these
nodes will be distributed into multiple zones by default, depending on the relative space available in each zone. You also have
the ability to distribute a five node ordering service yourself by unselecting the default option to have the zones chosen for you
and distributing these nodes into the zones you have available. If you are deploying a redundant node (that is, another peer
when you already have one), it is a best practice to deploy this node into a different zone. You can check which zone the other
node was deployed to by opening the tile of the node and looking under the Node location. Alternatively, you can use the APIs
to deploy a peer or orderer to a specific zone. For more information on how to do this with the APIs, see Creating a node within a
specific zone.

Note: The CA zone selection is only available when the default database type SQLite is used and your cluster is configured
with multiple zones.
Other CA considerations: If you have multiple zones configured for your Kubernetes cluster, when you create a new CA with a
PostgreSQL database and replica sets, an anti-affinity policy ensures that the CA replica sets are automatically configured across
the zones. Replica sets are represented as shaded CA boxes in the diagram above. Adequate resources must exist in the other
zones in order for the anti-affinity policy to be used.
Multizone-capable storage:
Before you deploy any nodes, you have the additional option to configure your Kubernetes cluster to use multizone-capable
storage as your persistent storage. 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, if a zone failure occurs, peers and ordering nodes can come up in another zone,
with their associated storage intact, ensuring high-availability. In order to leverage this capability with the IBM Blockchain
Platform, you need to configure your cluster to use SDS (Portworx) storage. 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.
This scenario uses redundant peers, ordering nodes, and CAs across multiple worker nodes and multiple zones, which protect
against zone failure, but does not protect from an unlikely entire region failure.
Important: If you choose to use a multi-zone configuration for CA, peers, or ordering nodes, then you are responsible for
configuring the storage for each zone and set the node affinity to zones.
Multi-region HA
This scenario offers the highest level of HA possible.
Figure 3. Blockchain HA multi-region options
Region failure.
Multi-region clusters with multiple work nodes and anti-affinity:
The likelihood of a full regional failure is low. However, to account for this failure, you can set up multiple clusters in different
regions where each cluster has its own linked console. If an entire region fails, redundant peers or ordering nodes in the other

regions can service the work load. For production environments, configuring your blockchain peers and ordering nodes across
multiple regions provides the maximum HA coverage available.
This scenario uses redundant peers and ordering nodes across multiple worker nodes in multiple regions, which provide the
highest degree of HA. This approach is also a recommended scenario for a production network when your resiliency
requirements merit the investment. The five ordering nodes are spread across three clusters in a 2-1-2 pattern, meaning two
nodes in Region 1, one node in Region 2, and two nodes in Region 3. This configuration allows any single region, or all of the
ordering nodes in a region to go down, while still maintaining a quorum of nodes in the Raft cluster.
See the topics on setting up multi-region HA deployments for steps to configure your IBM Blockchain Platform peers and
ordering nodes across multiple regions.
Disaster recovery (DR)

The most important step for disaster recovery is to configure your environment across multiple regions as documented in the
previous section. Multi-region configuration ensures that your environment can handle a datacenter or regional disaster with
zero downtime or data loss. However, this does not protect against data corruption or accidental deletion. To do this, you may
want to also take periodic backups.
It is recommended that you regularly back up the storage associated with every deployed component. Because the ledger is
shared across all the peers and ordering nodes, taking regular backups is critical. For example, if incorrect data is accidentally
propagated to a peer's ledger or if data is mistakenly deleted, the incorrect data might spread to the ledgers of some other
peers. This would require the restoration of the ledgers of all the peers from an established backup point to ensure
synchronicity. You can decide how often to perform the backups based your recovery needs, but a general guideline would be to
take daily backups.
Important: All nodes must be stopped in order to ensure a reliable backup.
Storage solution Guidance

provider
IBM Cloud storage You can leverage the capability provided by IBM Cloud Kubernetes service or OpenShift.
solution
Portworx While a snapshot capability is available for taking backups, in order to get a reliable backup, the
nodes must be stopped.
Table 2. Backup recommendations for storage
When you need to restore a backup, the backups would need to be restored on every component across your network.
If you are using CA replica sets and your PostgreSQL database resides in IBM Cloud, backups are included in the service. See the
topic on Managing Backups for more information. Otherwise, you need to work with your third-party PostgreSQL database
provider to manage the database backups according to your DR needs.
Backup and recovery

For information about backing up your components and how to recover corrupted components or networks, see Backing up and
restoring components and networks.
Setting up multiregion High Availability (HA) deployments for peers

Multiregion HA configuration provides the highest degree of HA coverage that is possible. Deploying peers across multiple

geographic regions ensures that if any one region becomes unavailable, the peers in other regions can continue to transact. Note
that multiregion HA support for CAs and the ordering service is not currently available.
Overview
To set up multiregion HA support for peers, you need to complete the following tasks:
Create multiple blockchain service instances that are each bound to a Kubernetes cluster in a different region.
Use the blockchain console or APIs to create your blockchain nodes in the different regions.
Use the node export and import actions to manage the nodes from a single console.
Configuration steps
To configure multiregion HA by creating redundant peers for each organization, complete the following steps when you configure
your blockchain network:
1. Create three Kubernetes clusters in IBM Cloud in the regions you prefer. These clusters can be located in any region you
want, although for high performance they should be relatively close together. For example, the regions, East Coast US, and
West Coast US, and Canada are better than the regions, West Coast US, London, and Tokyo.
2. Deploy a new IBM Blockchain Platform instance on the cluster in one of the regions. If you are using a Kubernetes cluster
on IBM Cloud, you need to link the service instance to the cluster. Repeat these steps in the second and third regions.
When you are finished, you have three separate IBM Blockchain Platform instances linked to three separate clusters, each
in a different region, and three separate consoles.
Important: This tutorial assumes that an ordering service exists with a channel defined that the peers can join.
Step one: Create the peer organization's CA and metadata in cluster one
1. Deploy a CA in the first cluster by following the instructions in the Build a network tutorial for Creating your peer
organization's CA. Make note of the values of the CA enroll ID and secret because you need to provide those values when
you import the CA into other clusters.
2. After the CA tile status indicator is green, Running, follow the instructions to Register identities with your CA. In those
instructions, you create two identities, one for the peer and another for the peer's organization admin identity.
3. Create the peer's organization MSP definition for the peer's organization in the first cluster.
4. Export the peer's organization definition and share it with an ordering service admin.
5. Similarly, the ordering service admin needs to follow the steps to import the peer's organization and add it to the
consortium. They will also need to complete the steps in those instructions to export the ordering service to a JSON file.
6. Import the ordering service JSON file to your console.
7. Create a peer in the first cluster.
8. Join your peer to the channel. Make this peer an anchor peer, as this allows service discovery, private data, and peer
gossip to be used. For HA, it is recommended that you add each redundant peer as an anchor peer. That way if one of the
peers is unavailable, gossip between organizations can continue.
9. Install and Propose smart contract on your peer.
After the smart contract definition has been proposed, it must be approved and committed.
Step two: Export the metadata and identities from cluster one
1. Export the CA definition to a JSON file.
Open the CA in the Nodes tab.
Click the download icon to generate the CA JSON file from your browser session.
2. Export the peer's organization MSP definition to a JSON file.
Open the MSP definition in the Organizations tab.
Click the download icon on the tile.
3. Export the peer's organization admin identity from your wallet.
Navigate to the Wallet tab.

Click the peer's organization admin identity and then click Export identity.
A JSON file that contains the organization admin certificates is created. Make note of the file name and secure the
file, because it is required when you create additional peers in your other clusters.
Step three: Import the metadata and identities in to cluster two and three
1. In clusters two and three, import the CA JSON file that you exported from cluster one.
2. If you will need to use the CA to register other identities, you need to open the imported CA and associate the CA
administrator enroll ID and secret that you used when you deployed the CA on cluster one.
3. Import the peer organization MSP definition JSON file that you exported from cluster one.
In the Organizations tab click Import MSP definition.
Click Add file to upload the JSON file.
Click I have an administrator identity for the MSP definition checkbox to allow you to use this MSP definition when
you create new peers in other zones.
Click Import MSP definition.
4. Import the organization admin identity JSON file that you exported from cluster one into the console wallet on clusters
two and three.
5. In clusters two and three, import the ordering service JSON file to your console.
Step four: Create new peers in cluster two and three and join a channel
1. In clusters two and three, use the CA to register a new peer user, following the same steps that you took when you
registered the peer identity in cluster one. You only need to create the peer users, you do not need to re-create the
organization admin identity because you will import that in the next step.
2. Create new peers, by using the CA you that imported from cluster one as the peer's CA. Use the peer organization MSP
that you imported from cluster one as the peer organization MSP definition.
3. In cluster two and three, you can now repeat the steps that you ran to join the peers to the same channel as the peer in
cluster one.
4. After you install the smart contract on these redundant peers, they are able to transact and query the ledger.
5. Again, if you plan to use service discovery, private data, and peer gossip, you need to make each redundant peer an
anchor peer.
Your network is now configured such that a failure in any single region will not affect the peer workload.
To maximize your HA even further, consider the following additional options:
Export the peers that you created in clusters two and three and import them into the console in cluster one. Then,
everything can be managed from a single cluster.
However, cluster one can fail. Therefore, to further account for a cluster failure, you can import all your peers into each of
the three consoles. Then if a cluster containing any one console fails, everything can still be managed from the consoles in
the other two clusters.
Setting up multiregion High Availability (HA) deployments for the ordering service
In this tutorial, you learn how to set up a Raft ordering service with five ordering nodes that span multiple regions for maximum
high availability.

Figure 1. A diagram that shows the architecture of a multiregion ordering service
The diagram shows a multiregion ordering service that includes five ordering nodes that are spread across three Kubernetes
clusters in three different regions. For simplicity, this tutorial assumes that all the ordering nodes are contributed by the same
organization. The setup requires a single Certificate Authority (CA), created in one cluster and imported into the blockchain
consoles on the other two clusters.
Note: Throughout this tutorial we refer to two types of nodes: "ordering nodes" and "worker nodes". Ordering nodes
belong to a Raft ordering service cluster. Worker nodes refer to the Kubernetes component that hosts the pods where the
ordering nodes are deployed.
After you understand how to spread the ordering nodes across regions, it is possible for separate organizations to contribute
ordering nodes and generate certificates by using their own CAs. This advanced configuration is not covered in this tutorial, but
you can learn more about it in the Next steps.
Although you cannot choose which worker node an ordering node is deployed to, the console is configured with an anti-
affinity policy. This means that for high availability, whenever you deploy a blockchain node on a multi-node cluster, the
console attempts to spread ordering nodes that belong to the same organization across the worker nodes if sufficient resources
are available. If your cluster is configured with multiple zones, you can designate which zone the ordering node is deployed to
when you create it, or you can let the console choose for you. In this case, it also leverages the anti-affinity policy across zones.
A minimum of five ordering nodes is recommended for a production ordering service. In Raft, a majority of the total number of
nodes is needed to form a quorum. In other words, if you have one node, you need that node available to have a quorum
because the majority of one is one. Similarly, if you have two nodes, you will need both available, since the majority of two is two.
In a similar vein, the majority of five is three. This means that in a five node configuration, the loss of two nodes can be tolerated
and ensures zero downtime. You can see in the diagram that Region 1 contains two ordering nodes, Region 2 contains one
ordering node, and Region 3 contains two ordering nodes. Spreading the nodes across the regions guarantees that if any single
region goes down, or if the ordering nodes within it need to be offline for maintenance, that quorum can be maintained by the
nodes in the other regions.
The tutorial walks you through the following steps:
1. Deploy the ordering service in Region 1.

2. Add a new ordering node in Region 2.
3. Add two new ordering nodes in Region 3.
4. Update the ordering service in Region 1, Region 2, and Region 3.

Before you begin
This tutorial assumes that you have three Kubernetes clusters that are deployed across three different regions and that you have
linked a blockchain service instance to each of those clusters.
Tip: Choose the regions of your Kubernetes clusters carefully. While it is fine for the ordering nodes to span regions,
transaction latency can occur when the cluster regions are geographically far apart. For example, it is not recommended
to deploy some ordering nodes in Tokyo, some in Australia, and some in the United States.
Create an IBM Blockchain Platform service instance in IBM Cloud.
Deploy an instance of the IBM Blockchain Platform in each cluster and verify that you can log in to the console.
Build a network tutorial
We assume that you are already familiar with the console and using it to deploy a CA, register users, enroll identities, create
a Membership Service Provider (MSP), and create an ordering service. If you have not used the console before, you should
review the Build a Network tutorial because a similar process is used in throughout the following instructions.
Step 1: Deploy the ordering service in Region 1

In this section, we create a single-node ordering service and then add a second ordering node as highlighted in yellow in the
diagram below:
Figure 2. Create the ordering service and second ordering node
Before we can deploy the ordering service, we create the ordering organization CA, register the ordering organization admin
users and the ordering node user, and create the organization Membership Service Provider (MSP). The bulk of the work to set
up an ordering service is performed in this section, making it simple in later steps to add ordering nodes from other regions.
Create the ordering service CA

For simplicity, we create an ordering service where all the ordering nodes belong to the same organization. Therefore, we create
a single CA and register and enroll the identities for each ordering node with the CA. After you have logged in to the console in
Region 1 complete the following steps:
1. Navigate to the Nodes tab and click Add Certificate Authority.

2. In this step, we're creating a CA, as opposed to importing one, so make sure that the option toCreate a Certificate
Authority is selected. Then click Next

3. Give this CA a unique display name, Multiregion OS CA .
4. Provide the CA administrator enroll ID and corresponding secret. For purposes of this tutorial, we use admin and
adminpw.
5. You can ignore the Advanced deployment options, they are not relevant to this tutorial.
6. Review the Summary page, then click Add Certificate Authority.
Important: Depending on your cluster type, deployment of the CA can take up to ten minutes. When the CA is first
deployed, the status indicator box in the CA tile is a flashing gray box. When the CA is successfully deployed and is
running, this box turns green, indicating that it is "Running" and can be operated from the console. Before proceeding with
the steps below, you must wait until the CA status is "Running". If the gray box stops flashing, try reloading the page in
your browser to refresh the status.
Associate the CA admin identity

Each CA node is created with a CA admin identity. You use the admin identity to register new users with your CA and generate
certificates. Before you can use the console to operate your CA, you need to associate the CA admin identity with the CA node
itself.
After the CA is running, as indicated by the green box in the tile, complete the following steps:
1. Click the Multiregion OS CA tile in the Nodes tab. Then, click Associate identity on the CA overview panel.
2. On the side panel that opens, provide the Enroll ID of admin and Enroll secret of adminpw that you specified in the
preceding section. For the Identity display name, you can use the default value of Multiregion OS CA Admin .
3. Click Associate identity to add the identity into your console Wallet and associate the admin identity with your CA.
Task: Associate identity

Field Display name Enroll ID Secret
Enroll ID Multiregion OS CA Admin admin adminpw
Table 1. Associate CA admin identity
You should be able to see the CA admin in your Wallet.
Task: Check your Wallet

Field Display name Description
Identity Multiregion OS CA Admin Multiregion OS CA admin identity
Table 2. Check your Wallet
Use your CA to register identities

Each ordering node in the ordering service needs a certificate and private key to participate in the blockchain network. You also
need to create an admin identity for the ordering service organization that you can use to manage the ordering service. We use
the CA to register these identities:
An organization admin: This identity allows you to operate the ordering nodes from the console.
ordering node user: This is the registered user that each ordering node will use. When the ordering node is subsequently
created, this user is enrolled, meaning that a certificate and private key are generated for the node.
Because you have already associated the CA admin identity, you can now use the CA tile to create these identities by completing
the following steps:

1. Click the Multiregion OS CA tile in the Nodes tab and ensure the admin identity that you created for the CA is visible in
the table. Then click the Register user button.
2. First we'll register the organization admin, which we can do by giving anEnroll ID of osadmin and a secret of osadminpw.
Then, use the Type drop-down to set the type for this identity as admin. You can ignore the Maximum enrollments field. If
you want to learn more about enrollments, see Registering identities. Click Next.
3. This tutorial does not configure attributes on identities. Click Register user.
4. After the organization admin has been registered, repeat this same process for the identity of the ordering nodes. Use the
information in the table below to register the ordering node user for the ordering nodes with an Enroll ID of os1 and
secret os1pw. This is an ordering node identity, so be sure to select orderer from the Type drop-down list.
5. You can also register identities of type orderer with the TLS CA. Completing this optional step for your orderer's admin
identity allows viewing additional channel details for the orderer nodes that use this identity. Repeat steps 1-2 above,
changing the Certificate Authority drop-down selection from Root Certificate Authority to TLS Certificate
Authority.
Task: Create a CA and register users

Field Description Enroll ID Secret Type
Create CA Multiregion OS CA admin adminpw client
Register users Ordering Service admin osadmin osadminpw admin
Ordering Service node 1 identity os1 os1pw orderer
Table 3. Register users with CA
Tip: You could register a new user for each ordering node, but to keep things simple we will reuse the same user enroll ID
and secret for each ordering node. Reusing the enroll ID is acceptable in this case because a unique certificate is
generated when the ordering node is created and the identity is enrolled. But it is important to ensure that you have not
restricted the maximum enrollments for the user when it is initially registered so that a new certificate can be generated
when the user is enrolled when each ordering node is created. The default value of maximum enrollments is unlimited .
Create the ordering service organization MSP definition

Create your ordering service organization MSP definition and specify the admin identity for the organization. After we have
registered the ordering service admin and ordering service users, we need to create the MSP ID and enroll the osadmin user
that we registered as the admin of our organization.
1. Navigate to the Organizations tab in the left navigation and click Create MSP definition.
2. Enter Multiregion OS MSP as the organization MSP display name and mrosmsp and as the MSP ID. Click Next.
3. Under Root Certificate Authority details, specify the CA you used to register the identities in the previous step,
Multiregion OS CA , and click Next.
4. Under Enroll ID and Enroll secret, select osadmin, and enter its associated secret, osadminpw.
5. Click the Generate button to enroll this identity as the admin of your organization and export theMultiregion OS MSP
Admin identity to the Wallet.
6. Click Export to export the admin certificates to your file system and then clickNext.
7. Review the information on the Summary panel and click Create MSP definition.
8. After the MSP is created, click on its tile and then clickExport to download the Multiregion OS MSP to your
local filesystem as a JSON file. You will need to send this MSP to all operators of the blockchain consoles in other regions.
Task: Create the ordering service organization MSP definition

Display name MSP ID Enroll ID Secret
Create Organization Multiregion OS MSP mrosmsp

Root CA Multiregion OS CA
Org Admin Cert osadmin osadminpw
Identity Multiregion OS MSP Admin
Table 4. Create the ordering service organization MSP definition
After you create the MSP, you should be able to see the ordering service organization admin in yourWallet, which can be
accessed by clicking the Wallet tab in the left navigation.

Identity Multiregion OS CA Admin Multiregion OS CA admin identity
Identity Multiregion OS MSP Admin Multiregion OS MSP admin identity
Table 5. Check your wallet
Create single node ordering service in Region 1.

1. From the Nodes tab, click Add ordering service.
2. Make sure that the option to Create an ordering service is selected. Then, clickNext.
3. Give your ordering service a Display name of Multiregion Ordering Service .
4. Choose One ordering node because we are creating a single node ordering service and then adding the other four nodes
to it.
5. For more granular control of which zone the node gets deployed in, if your Kubernetes cluster is configured for multiple
zones the console includes an advanced deployment option labeled Deployment zone selection. Selecting this option
allows you to place the node in a specific zone inside your cluster. Or the anti-affinity policy of the console will
automatically deploy your ordering nodes to different worker nodes within each zone based on the resources available.
Learn more about the available zone selection options. If you prefer to let the system choose the zone for you, you can
leave this advanced option unchecked. Click Next.
6. On the Add ordering service page
Select Multiregion OS CA as your CA.
Then, select the enroll ID for the node identity that you created for your ordering service from the drop-down list,
os1.
Enter the associated secret, os1pw.
Select your MSP, Multiregion OS MSP from the drop-down list.
For purposes of this tutorial, you can skip the TLS CSR hostname option.
In the Fabric version drop-down list, select the latest available version, as it will contain the latest bug fixes.
Click Next.
7. The Associate identity step allows you to choose an admin for your ordering service. SelectMultiregion OS MSP Admin
and click Next.
8. Review the Summary page and click Add ordering service.
Task: Create an ordering service

Create ordering service Multiregion Ordering Service mrosmsp
CA Multiregion OS CA

Ordering Service Identity os1 os1pw
Administrator certificate Multiregion OS MSP
Associate identity Multiregion OS MSP Admin
Table 6. Create an ordering service
It takes several minutes for the ordering service to be deployed to yourRegion 1 cluster. After the ordering service has been
successfully deployed, you are able to see it on the Nodes panel with a green status indicator. You may need to refresh your
browser.
Add second ordering node in Region 1

Now we can create a second ordering node in Region 1 and add it to the ordering service. The steps are similar, but this time
they are performed from inside the ordering service itself.
1. Navigate to the Nodes tab.

2. Scroll down to the ordering service that you created and click the tile to open it.
3. Click the Ordering nodes tab. Notice a single ordering node was created in the previous section. We add a second node by
clicking Add another node.
4. Click Create an ordering node and Next.
5. Provide a name for this ordering node, OS2-Region1.
6. If you want to control which zone the node is created in, select the advanced deployment option that is labeled
Deployment zone selection, otherwise you can leave this advanced option unchecked. Click Next.
7. On the Add another node page:
Then, select os1 as the enroll ID for the node
As before, skip the TLS CSR hostname option.
In the Fabric version drop-down list, select the latest available version, as it will contain the latest bug fixes.
Click Next.
8. Review the Summary page and click Add another node.
Task: Add second ordering node

Display name MSP Enroll ID Secret
Create ordering node OS2-Region1 Multiregion OS MSP
Table 7. Create second ordering node
Add the OS2-Region1 node to the orderer system channel

If your cluster does not use a system channel, skip this step. To verify if a cluster uses a system channel, click the cluster tile and
check the Orderer Type.
To complete the process of adding the node, you need to add it to the consenter set of the system channel. After the ordering
node has been successfully added, a new tile with the name of OS2-Region1 appears on the Multiregion Ordering Service

page with the label "Requires attention". This state reflects the fact that, while the node creation process has been successful,
the node is not yet part of the consenter set of the system channel. The node must be added to the system channel before it can
be added to any of the application channels.
Tip: Recall that the "consenter set" refers to the ordering service nodes actively participating in the ordering process on a
channel, while the "system channel", which is managed by the ordering service, forms the template for application
channels.
To add the node you created to the system channel, click the OS2-Region1 node. You will see an Add node to ordering service
button. Click this button. After the node has been added to the ordering service, the node is now part of the system channel.
Note that it will take a few minutes for the new node to sync with ordering service in the system channel. During this time,
you may see a message that your ordering service is down. This is normal --- the ordering service must come down while the
new node is syncing. After the node tile status is green, proceed to the next section.
Export components
In your Region 1 blockchain console, you have now configured a CA for the ordering service and registered the orderer
organization admin as well as an orderer user for the ordering nodes. You created an organization MSP definition that was used
to deploy a single-node ordering service and then added a second node from Region 1 to the ordering service. Next, we need
to export these components to your file system so they can be imported to the blockchain consoles in the Region 2 and Region 3
clusters.
When you created the orderer organization MSP, you already exported the Multiregion OS MSP definition and the
Multiregion OS MSP Admin identity, you also need to export the CA and the ordering service:
1. From the Nodes tab, open the Multiregion OS CA tile and click Export .
2. From the Nodes tab, open the Multiregion Ordering Service tile and click Export .
These actions download the components in JSON format to your local file system. You will need to share these four files with the
operators of the blockchain console in Region 2 and Region 3.
Step 2: Add a new ordering node in Region 2

Now that the ordering service is available, we can add nodes to it from the two other regions.
In this section, we create a third ordering node and then add it to the system channel (if applicable) as highlighted in yellow in
the diagram below:

Figure 3. Create a third ordering node in Region 2
Because all of the actions in this section are performed from the blockchain console inRegion 2, log in to the Region 2 console
now.
Import components
Before you can use the console in Region 2 to add an ordering node to the ordering service, you need to import the components
that you set up in the previous cluster.
Tip: After you import a node into your console, you can use it create or manage other components in your console. But it
is important to understand that the original node remains physically located in the console in Region 1. This means that if
you need to view the logs of an imported node, you would need to do that from the cluster in Region 1 where it resides.
1. Import the CA.

From the Nodes tab, click Add a Certificate Authority, then Import an existing Certificate Authority.
Click Add file and browse to the Multiregion OS CA_ca.json file that you exported from the console in Region 1
and click Add Certificate Authority.
Open the imported Multiregion OS CA tile.
Click Associate identity.
Specify the enroll ID and secret we used when we created the CA, admin and adminpw then Associate identity.
2. Import the Ordering service.
From the Nodes tab, click Add ordering service, then Import an existing ordering service.
Click Add file and browse to the Multiregion Ordering Service_orderer.json file that you exported from the
console in Region 1 and click Add ordering service.
3. Import the orderer organization msp.
From the Organizations tab, click Import MSP definition and then click Add file.
Browse to the Multiregion OS MSP_msp.json file that you exported from the console in Region 1 and click
Import MSP definition.
4. Import the MSP admin identity.
From the Wallet tab, click Add identity then Upload JSON.
Browse to the Multiregion OS MSP Admin_identity.json file that you exported from the console in Region 1
and click Add identity.
Add third ordering node from Region 2

Now we are ready to create a third ordering node that resides inRegion 2 and add it to the ordering service. The steps that are
required are largely repeated from when we added the second ordering node to the ordering service in Region 1.

2. Scroll down to the Multiregion Ordering Service ordering service that you imported and click the tile to open it.
3. Because the ordering service was not created in this console, you need to associate the admin identity with it. Click
Associate identity and then select the Multiregion OS MSP Admin and click Associate identity.
4. Click the Ordering nodes tab where you can see the two ordering nodes contributed by the console inRegion 1. Click Add
another node to add a new node from Region 2.
7. Again you can click the advanced deployment option that is labeled Deployment zone selection if you want to choose
the zone where this node is deployed. Otherwise, you can leave it unchecked and let the system choose for you. Click
Next.
Then, select os1 as the enroll ID for the node identity.
For purposes of this tutorial, you can skip the TLS CSR hostname option.
Select the latest available Fabric version from the drop-down list, as it will contain the latest bug fixes and click
Next.
9. Review the Summary page and click Add another node.
Task: Add third ordering node

Create ordering node os3-Region2 Multiregion OS MSP
Table 8. Create third ordering node
To complete the process of adding the node to a system channel, you need to add it to the consenter set of the system channel.

Just as when we performed these steps in the console in Region 1, a new tile with the name of OS3-Region2 appears on the
Multiregion Ordering Service page with the label "Requires attention". Again, this state reflects the fact that, while the node
creation process has been successful, the node is not yet part of the consenter set of the system channel. The node must be
added to the system channel before it can be added to any of the application channels.
Click the node to open it and then clickAdd node to ordering service. After the node has been added to the ordering service,
this third node is now part of the system channel.
Wait until the OS3-Region2 node tile status turns green before proceeding to the next section.
Export the ordering node

After this third ordering node has started successfully as indicated by the green status indicator on its tile, we need to export the
node so that later it can be imported into the ordering service in the Region 1 and Region 3 consoles.

Open the new ordering node and click Export to download the configuration to a OS3-Region2_orderer.json file
on your local system. Share this file with the operators of the consoles in Region 1 and Region 3 so they can import it into their
ordering service in the last step of this tutorial.
Step 3: Add two new ordering nodes in Region 3

In this section, we largely repeat the instructions performed in Region 2. The major difference is that Region 3 will contain two
ordering nodes, highlighted in yellow in the following diagram, whereas in Region 2 there is only one ordering node. Along with
the two nodes in Region 1 and one node from Region 2, this configuration will complete the recommended minimum number of
five ordering nodes for a production ordering service.
Figure 4. Create fourth and fifth ordering nodes in Region 3
Because all of the actions in this section are performed from the blockchain console inRegion 3, log in to the Region 3 console
now.
Import components
Repeat the steps to import the console components fromRegion 1, but this time import them into the Region 3 console:
1. Import the CA.

From the Nodes tab, click Add a Certificate Authority, then Import an existing Certificate Authority.
Click Add file and browse to the Multiregion OS CA_ca.json file and click Add Certificate Authority.
Open the imported Multiregion OS CA tile.
Click Associate identity.
Specify the enroll ID and secret we used when we created the CA, admin and adminpw, then Associate identity.
2. Import the Ordering service.
From the Nodes tab, click Add ordering service, then Import an existing ordering service.
Click Add file and browse to the Multiregion Ordering Service_orderer.json file and click Add ordering
service.
3. Import the orderer organization msp.
From the Organizations tab, click Import MSP definition and then click Add file.
Browse to the Multiregion OS MSP_msp.json file and click Import MSP definition.
4. Import the MSP admin identity.
From the Wallet tab, click Add identity then Upload JSON.
Browse to the Multiregion OS MSP Admin_identity.json file and click Add identity.
Add fourth and fifth ordering nodes from Region 3

Almost done. Let's create the last two ordering nodes that will reside inRegion 3 and add them to the ordering service:

2. Scroll down to the Multiregion Ordering Service ordering service that you imported and click the tile to open it.
3. Because the ordering service was not created in this console, you need to associate the admin identity with it. Click
Associate identity and then select the Multiregion OS MSP Admin and click Associate identity.
4. Click the Ordering nodes tab where you can see the two ordering nodes contributed by the console inRegion 1. Click Add
another node to add a new node from Region 3.
7. Again, if you want to choose the zone where this node is deployed, click the advanced deployment option that is labeled
Deployment zone selection. Otherwise, leave it unchecked and let the system choose for you. ClickNext.
Then, select os1 as the enroll ID for the node identity.
For purposes of this tutorial you can skip the TLS CSR hostname option.
Select the latest available Fabric version from the drop-down list, as it will contain the latest bug fixes and click
Next.
9. Review the Summary page and click Add another node. Don't worry about adding OS4-Region3 to the system channel
yet. We'll do that after adding the last ordering node.
Task: Add fourth ordering node

Table 9. Create fourth ordering node
Repeat this exact same set of steps for the fifth ordering node, but give it the name OS5-Region3 .
Task: Add fifth ordering node

Table 10. Create fifth ordering node
Add the ordering nodes to the orderer system channel

Add both ordering nodes to the consenter set of the system channel. Click each new ordering node, thenAdd node to ordering
service. After the nodes have been added to the ordering service, the nodes are now part of the system channel.

Export the ordering nodes
After these two ordering nodes have started successfully as indicated by the green status indicator on its tile, we need to export
the node so that they can be imported into the ordering service in the Region 1 and Region 3 consoles.
Open both new ordering nodes, OS4-Region3 and OS5-Region3 , and click Export to download the configuration
to a JSON file on your local system. Share these files with the operators of the consoles in Region 1 and Region 2.
Update the ordering service in Region 1, Region 2, and Region 3.

The final step is to update the ordering service in each region with the ordering nodes that were generated in the other two
regions.
1. In the Region 1 console, import the os3-Region2, os4-Region3, and os5-Region3 files.
From the Nodes tab, open the Multiregion Ordering Service tile and click the Ordering nodes tab.
Click Add another node and then Import an existing ordering node.
Click Add file and browse to the JSON file for one of the exported ordering nodes.
Repeat this process for the other two ordering node JSON files.
2. In the Region 2 console, import the os4-Region3, and os5-Region3 files by repeating the same steps that you used in
the Region 1 console.
3. In the Region 3 console, import the os3-Region2 file by repeating the same steps.
The ordering service is now synchronized in each console across each region and can be used to create application channels
between consortium members.
To summarize, anytime a new ordering node is added to the ordering service in a console, it needs to be exported and then
imported into the ordering service in the consoles in the other regions. When you subsequently create an application channel
based on this ordering service, under the advanced options, you can select which ordering nodes to include in the consenter set.
Therefore, it is important that your console is up to date with all of the available ordering nodes before creating the channel in
order to include them to the channel consenter set.
The following screen capture shows what the ordering service looks like on the console inRegion 1. Notice the Imported label
on the three tiles from the other clusters. The ordering service should be identical in Region 2 and Region 3 except for the
Imported labels, since they will vary by region.
Figure 5. Multiregion ordering service
Next steps
Create application channels
The multiregion ordering service is now configured for HA across regions and is ready for peer organizations to create

application channels. If the peers do not reside in any of the consoles that are used in this tutorial, you need to export our
five-node ordering service and import it along with the orderer organization MSP into the console where the peer resides.
This allows the peer organization admin to create application channels that are based on the ordering service. For
instructions on how to create an application channel, see the Build a network tutorial.
Multi-organization ordering service
For simplicity, we use a single organization for all five ordering nodes in this tutorial. But it is possible when you build an HA
ordering service that multiple organizations will want to contribute their own ordering nodes to the ordering service. In that
case, the process is largely the same. The major difference is that each organization that wants to contribute an ordering
node needs to have their own CA and own organization MSP definition. The process to add ordering nodes from separate
organizations is described in the Adding and removing ordering service nodes topic and the resulting architecture in this
case would be similar to:
Figure 6. Multiregion, multi-organization ordering service
Clean up
Want to start fresh? You can remove the following resources that you created as a part of this tutorial:
From the Nodes tab, open the Multiregion OS CA and click the trash can .
From the Organizations tab, open the Multiregion OS MSP and click the trash can .
From the Nodes tab, open the Multiregion Ordering Service and click the trash can .
From the Wallet tab, open Multiregion OS CA Admin and click Remove identity.
From the Wallet tab, open Multiregion OS MSP Admin and click Remove identity.
Building a high availability Certificate Authority (CA)

Because redundancy is required to achieve high availability (HA) networks, you can use the IBM® Blockchain Platform console to
configure a CA for high availability.
Target audience: This topic is designed for network operators who are responsible for creating, monitoring, and managing the
blockchain network.
Important: If you are using IBM Blockchain Platform for IBM Cloud, HA CA configuration is only available in paid
Kubernetes clusters on IBM Cloud.
Configuring CA replica sets

When a Kubernetes pod becomes unavailable, Kubernetes immediately attempts to restart it. However, if your SLA requires zero
downtime for your CA, you can configure replica sets for your CA. A replica set is a Kubernetes mechanism that is used to
guarantee the availability of the pod. The use of replica sets ensures that multiple replicas of the pod are running at all times. If
one of the CA replicas becomes unavailable, Kubernetes immediately switches to another CA replica, therefore there is no
downtime while you wait for the pod to restart. The replica uses data from the same shared database so that the CA can
continue to seamlessly process requests. If CA replica sets are required for your business, the IBM Blockchain Platform requires
the CA to use an instance of a PostgreSQL database. Thus, before you can configure CA replica sets, you are responsible for
configuring an instance of the PostgreSQL database.
Deploying a PostgreSQL database

PostgreSQL is a widely available open source relational database management system. The CA uses the database to store
certificates (public keys only) and identities that are registered with the CA. Customers need to provision their own PostgreSQL
database instance in IBM Cloud or from a third-party provider. When you deploy a new CA by using the blockchain console or
APIs, you need to provide the connection information for the database. Each CA needs its own PostgreSQL database.
Considerations
CA replica sets are only possible when the PostgreSQL database is selected for the CA. The SQLite database is not
supported for use with CA replica sets.
Because you cannot switch a CA database from SQLite to PostgreSQL, only new CAs that use PostgreSQL can be
configured to be HA. Likewise, after a CA is deployed and configured to use a PostgreSQL database, it cannot be
reconfigured to use a different PostgreSQL instance or later configured to use SQLite.
CA replica sets are automatically spread across your worker nodes in a single zone according to available resources.
Replica sets are not available across zones.
Because creating a CA replica set results in a new CA pod, when you configure an additional replica set, the CPU and
memory requirements for the CA are doubled. If three replica sets are required, then the total CPU and memory
requirements triple, and so on. However, the storage allocation does not change because all of the replica sets use the
same PostgreSQL database. When you configure your CA, you can specify how many replica sets to create.
The number of replica sets can be scaled up or down over time according to your availability needs.
Replica sets are only available when PostgreSQL is selected as the CA database.
The ability to deploy a CA to a specific Kubernetes cluster zone is only available when SQLite is selected as the CA
database.
Before you begin

You need to configure an instance of a PostgreSQL database. There are two options available in IBM Cloud:
Databases for PostgreSQL. See the Getting Started tutorial for information on provisioning an instance of the service.
Hyper Protect DBaaS for PostgreSQL. See the tutorial on Getting started with IBM Cloud Hyper Protect DBaaS for
PostgreSQL for setup instructions.
Use of a third-party PostgreSQL database is also supported. If the third-party database is configured to use TLS, you will need to
provide at least one server certificate. If SSL client authentication (mutual TLS) is enabled, you also need to provide a client
certificate and a client key in .pem format. More information on how to provide this information is provided in the steps that
follow.
Creating the PostgreSQL connection file

For all three PostgreSQL database options, you need to provide a file that contains the connection information to the PostgreSQL
database when you create the CA. The process to generate the file depends on whether the database resides in IBM Cloud or is
from third-party provider.
IBM Cloud Databases for PostgreSQL If you are using a PostgreSQL database from IBM Cloud Databases for PostgreSQL,
you need to generate Service Credentials from the PostgreSQL resources page in your IBM Cloud Databases for

PostgreSQL dashboard by completing the process in the following clip:
Save the credentials that you copied to a file of type JSON on your local system. When you create your CA, you need to
provide this file.
IBM Cloud Hyper Protect DBaaS for PostgreSQL If you are using a PostgreSQL database from IBM Cloud Hyper Protect
DBaaS for PostgreSQL, then you need to manually build the JSON file by using the following template:
{
"connection": {
"postgres": {
"hosts": [
{
"hostname": "db_hostname",
"port": "db_port"
}
],
"database": "db_name",
"authentication": {
"username": "db_admin_username",
"password": "db_admin_password"
},
"query_options": {
"sslmode": "verify-full"
},
"certificate": {
"certificate_base64": "ssl_root_cert"
}
}
}
}
Enter the corresponding hostname , port , database , username , password , and certificate_base64 values for your
PostgreSQL database:
hostname and port can be found in the Connect to database panel of the Hyper Protect DBaaS for PostgreSQL
dashboard.
database is the value that you enter for the Cluster name field when you provision the service instance. Note that
hyphen (-), space, and .db are not allowed in the name.
username and password are the values you enter for the Database admin name and Database admin password
fields when you provision the service instance.
certificate_base64 is the one-row string base64 format of the certificate value in the CA file, which you can
download from the Connect to database panel of the Hyper Protect DBaaS for PostgreSQL dashboard. Ensure to
convert the certificate value to one row.
Save this information to a JSON file on your local system so that is can be provided when you create your CA.

Third-party provider If you are using a third-party provider for your PostgreSQL database, then you need to manually build
the JSON file by using the following template:
{
"connection": {
"postgres": {
"hosts": [
{
"hostname": "db_hostname",
"port": 30000
}
],
"database": "db_name",
"authentication": {
"username": "db_user",
"password": "db_password"
},
"query_options": {
"sslmode": "verify-full"
},
"certificate": {
"certificate_base64": "tls_certificate"
},
"client": {
"certificate_base64": "client_tls_certificate",
"private_key_base64": "client_tls_private_key"
}
}
}
}
Enter the corresponding hostname , port , database , username , and password values for your PostgreSQL database.
Valid values for sslmode are listed in the Hyperledger Fabric CA PostgreSQL documentation.
The certificate and client fields are required only if you are using TLS to encrypt communications to the PostgreSQL
database. All certificate strings must be base64 encoded.
Important: If you are not using TLS, you need to remove the certificate and client elements from your JSON file.
If the third-party database is configured to use TLS, you will need to provide at least one servercertificate.
If SSL client authentication (mutual TLS) is enabled, you will need to provide thecertificate as well as the client
certificates, certificate_base64 and private_key_base64.
Save this information to a JSON file on your local system so that is can be provided when you create your CA.
Creating an HA CA
Create a new CA by using the IBM Blockchain Platform console.
1. Navigate to the Nodes tab on the left and click Add Certificate Authority.
2. Make sure that the option to Create a Certificate Authority is selected. Then click Next.
3. Give your CA a display name and enter your CA admin credentials by specifying a CA administrator enroll ID and secret.
4. Click the Database and replica sets selection checkbox under Advanced deployment options and click Next. If your
network is on IBM Cloud, this option is only available on paid clusters.
5. To use replica sets, select PostgreSQL as the CA database.
6. Click Add file and browse to the JSON file you created with the database connection information.
7. Choose the number of replica sets you need. Two replica sets ensure that if one CA replica becomes unavailable, the other
is always immediately ready to process requests. Three replica sets provide even greater redundancy. If two of the three
replica sets are unavailable, the third is ready to process requests. Because each additional replica set requires additional

CPU and memory, you need to ensure you have adequate resources available to accommodate the number you choose.
This value can be updated later as well.
8. You have the opportunity to configure resource allocation for the node. The resources that you specify here are used for
each replica set. If you want to learn more about how to allocate resources in IBM Cloud for your node, see this topic on
allocating resources.
9. Review the Summary page, then click Add certificate authority.

Data residency
Because blockchain networks are oblivious to the type of data that is processed, extra steps must sometimes be taken to keep
certain kinds of data secure. The most common requirement on data residency is associated with laws within certain countries,
which mandate that all data that is processed and stored in an IT system must remain within a specific country’s borders.
Similarly, some companies in highly regulated industries, such as government, healthcare, and financial services, require that
data must be stored entirely behind their firewall.
Blockchain networks allow multiple organizations to use a distributed ledger to transact and share data in a way that is trusted
and secure. However, this implies that data can be distributed across the nodes of the network and the regions where those
nodes reside. Organizations can use several options to separate data from the rest of the network and achieve data residency:
1. Private data collections on a shared channel

2. Private data collections on a separate channel
3. A separate channel with all of the nodes on the channel within a single country
4. A separate channel with only ordering nodes from one country
Each approach provides an increased level of isolation and protection for your data, but requires additional effort to implement
and manage. To help you understand how each option can be used to achieve data residency, we provide an overview of how
data is shared within a Hyperledger Fabric network. We then present an example use case to illustrate how organizations within
a blockchain consortium would use each option to separate their data and prevent it from leaving their region.
How data is shared within an IBM Blockchain Platform network

The architecture of Hyperledger Fabric that underlies the IBM Blockchain Platform is centered around three key components: an
ordering service (made up of ordering nodes), Certificate Authorities (CA), and peers. Additionally, organizations send
transactions to these nodes from client applications that use the Fabric SDKs. When considering data residency, it is important
to understand how these components interact with and store data.
Peers host ledgers and smart contracts, with the latter governing how changes to the former are made. Ledgers themselves
contain two distinct, though related, parts: a world state which records the current value of any key (such as an asset), and a
blockchain which contains a literal “chain of blocks” that contain the records of each transaction. Peers receive state updates in
the form of new blocks from the ordering service. They then use the blocks and the world state to confirm (or commit)
transactions, update the world state and add the log of transactions on the blockchain.
Ordering nodes form a Raft ordering cluster that comprises the ordering service of a channel. The ordering service literally
“orders” transactions into blocks that are sent to peers to be committed to their ledgers. Each ordering node stores a copy of the
blockchain portion of the channel ledger.
Channels are the place where organizations interact within a network. You cannot participate in a blockchain network without
joining a channel. Channels can be used by members of the network to create logical separation between business applications
and even to boost performance by limiting traffic. They can also be used by subsets of organizations in the consortium to
transact privately and separate data.
Peers maintain a separate ledger for each channel that they join. Only organizations that are members of the channel can join
their peers to the channel and receive ledger updates from the ordering service. As a result, each channel is bound to an
ordering service, which stores the blockchain portion of every channel ledger that it maintains. Client applications submit
transactions to the peers and ordering service of a given channel. These transactions are added to the transaction log within the
blockchain and include a read-write set that is used to update the key-value pairs in the world state.
If in-country data residency is a requirement, you need to consider the location of your peers and the ordering service, as well as
your client applications. You also need to know the location of the peers that belong to other organizations on your channels. If

you are using IBM Blockchain Platform for IBM Cloud, you can find the list of IBM Blockchain Platform regions and locations
where you and the members of your consortium can deploy your components.
A use case for data residency

We can use an example consortium to illustrate how data is distributed on the IBM Blockchain Platform, and to explore how
members can achieve data residency. The following figure contains a consortium with one ordering service and four
organizations. Each organization has one peer node. Two organizations, Org A and Org B, and the ordering service are located in
the United States. The other two organizations, Org C and Org D, are located in Germany. All four organizations are members of
and have joined their peers to channel X.
United States Germany
Org A Org C
Fabric SDK
Fabric SDK
Channel X
Client App 1
Ledger X Ledger X
Ledger
Ledger X

Client App 2 Client App 4

Ledger X Ledger X
Figure 1. An example blockchain consortium with one ordering service and four organizations. The four
organizations are all members of one channel, Channel X.
Each peer joined to channel X stores a copy of the channel ledger, which is displayed inFigure 1 as Ledger X. Because peers
from the United States and Germany are joined to the channel, the data on the channel ledger resides in both geographies. The
blockchain portion of the ledger is also stored by the ordering service that is located in the United States.
If two organizations in the consortium create a second channel, Channel Y, a second ledger is created and stored on the peers of
channel members. Only the organizations that joined the channel have a copy of the channel data.

Org A Org C
Fabric SDK
Fabric SDK
Channel X
Client App 1
Ledger X Ledger X
Ledger
Ledger X Ledger Y


Ledger X Ledger X
Channel Y
Ledger Y Ledger Y
Figure 2. Two organizations in the consortium have created and joined a second channel, Channel Y. A second
channel ledger is created and stored on the peers of Org B and Org D and the ordering service.
In Figure 2, Org B and Org D have joined channel Y. The peers of Org B and Org D now store a copy of ledger Y, in addition to
ledger X. Because the same ordering service was used to create channel X and channel Y, the ordering service now has a copy of
the blockchain portion of both channel ledgers. In both Figure 1 and Figure 2, data being created by applications in Germany is
stored in the United States, which is undesirable if data residency is required.
We can use the previous example to explore the options that organizations can use to achieve data residency. Assume that a
regulation in Germany requires some of the data that is created by Org C and Org D to remain within the country. The
organizations in Germany can use all four of the following options to prevent data from being stored in the United States.
Option one: Private data collections on a shared channel

Org C and Org D can use the private data feature of Hyperledger Fabric to prevent data from being distributed to all
organizations on the channel. Private data collections allow organizations to share state data peer-to-peer (via a gossip data
dissemination protocol) with other organizations that are authorized to read the collection. The data is stored in a private,
separate database on the peer. The ordering service is not involved and does not see the private data. Only a hash of the data in
the collection is added to the channel ledger and is stored on the peers of other channel members and the ordering service. This
allows organizations to verify private data if they want to make the transaction details public. To learn more, visit the Private
Data concept article in the Fabric documentation.

Org A Org C
Fabric SDK
Fabric SDK
Channel X
Client App 1
Ledger X Ledger X
CollectionOrg C-Org D
Ledger X
Org B Ordering Service Nodes

Org D


Ledger X Ledger X
Collection Org C-Org D
Figure 3. Org C and Org D use a private data collection to keep data from being distributed on channel X and from
leaving Germany. Hashes of data in the collection are stored on ledger X.
In Figure 3, Org C and Org D have created a private data collection, the OrgC-OrgD collection, that allows the organizations to
transact without having to share data with Org A, Org B, or the ordering service. The key-value state data inside this collection is
only stored on the peers of Org C and Org D and does not leave Germany. However, a hash of the data within the collection is
stored on ledger X and shared with the broader channel. This means that a hash of the data in the OrgC-OrgD collection is
stored on the peers and the ordering service in the United States.
When considering private data, it is important to understand the difference between hashed data and encrypted data.
Encryption uses a two-way function to transform data into a form that hides its original value, but can be converted back to the
original state. As an example, when data is sent over a network that is secured using TLS, the data is encrypted using a TLS
certificate. It is then sent over the network as crypto text, and then decrypted by the recipient. The encrypted text contains all
the original data, and can be decrypted using a private key. However, hashing is a one-way function that uses data to create a
unique string of numbers and letters. The hashed data cannot be converted back to the original form using the hash. To verify
the data that created the hash, a recipient needs to create a new hash of the original data using the same hash function, and
verify that the hash values match. A third party cannot use the hash without a copy of the original data.
It is important to be aware with this option that while Orgs A and B cannot see the actual ledger data because it is hashed, they
are still able to see that Orgs C and D are transacting and can see the volume of transactions that are occurring between them.
Also, consider that data inside a private data collection can be purged from the peers that store it. While data is stored on a
channel forever, collections allow members to specify how many blocks are committed to a channel before the private data is
purged. Once data is removed from the private data collection, the hash on the channel can no longer be used to verify the
transaction that created it. In the example network in Figure 3, Org C and Org D can use a block to live policy to ensure that
any data that does not need to persist forever is removed from the network entirely within a specified time period.
Option two: Private data collections on a separate channel

Org C and Org D can also use private data collections in the context of a separate channel to provide additional isolation for their
data. Creating a new channel, Channel Y in this case, ensures that the hash of the private data is only shared with the ordering
service, without being shared with other members of the consortium and stored on their peers.
Org A Org C
Fabric SDK
Fabric SDK
Channel X
Client App 1
Ledger X Ledger X
Ordering Service Org Collection Org C-Org D
Ledger Y
Ledger
Channel Y
Ledger X Ledger Y


Ledger X Ledger X
Collection Org C-Org D
Ledger Y
Figure 4. Org C and Org D form a separate channel, Channel Y, and use a private data collection. Hashes of data in
the collection are stored on ledger Y, and is only stored by the peers in Germany but not on the peers in the United
States.
In Figure 4, Org C and Org D have formed a new channel, Channel Y, that does not contain any members in the United States. As
a result, hashes of data in the OrgC-OrgD collection is stored on ledger Y instead of ledger X, and is not stored on the peers in
the United States. Because the ordering service is located in the United States, a hash of the data that is created in Germany still
leaves the country.
Creating a separate channel can prevent transaction details from being shared with other organizations in the consortium. If the
organizations in Germany used a shared channel, Org A and Org B would be able to see the number of transaction hashes that
are committed to the channel ledger by the private data collection. This might provide those organizations visibility into the fact
that Orgs C and D are transacting and the volume of transactions that are generated between them. Consider though that
forming a new channel requires additional management expense to create and update it. Forming a new channel also makes it
harder for Org C and Org D to share data with Org A and Org B.
Option three: A channel with all components in one country

Org C and Org D can also create a channel with all of the infrastructure within the same country. This requires that the peers
joined to the channel, the applications, and the ordering service all reside within the same region. In this scenario, none of the
data that is stored on the channel ledger will leave the region and be stored outside the country.

Org A Org C
Fabric SDK
Fabric SDK

Client App 1
Ledger X Ledger X
Ledger Y
Ledger
Channel Y
Ledger Y


Ledger X Ledger X
Ledger Y
Figure 5. Org C and Org D create a new channel using an ordering service located in Germany. All data is stored in
the country on Ledger Y.
In Figure 5, Org C and Org D have created a new channel for data that must not leave Germany. This requires the creation of a
new ordering service that is located in Germany to ensure that the orderer's copy of the channel ledger is stored inside the
country. Since in this case the ordering service, the OrgC-peer, and the OrgD-peer are located in Germany, Org C and Org D can
now keep the data public on the channel if they choose, or they could still decide to use private data collections to prevent the
full transaction data from being stored on the ordering service.
Creating a channel with all of the components in one country ensures that all of the data resides within one region, including the
key-value pairs, the blocks, and the hashes of any private data. However, this option requires the resources to maintain a new
channel and the costs that are associated with maintaining the ordering service.
Option four: A separate channel with only ordering nodes from one country
When you initially deploy an ordering service, you create a set of ordering nodes that will be available to the application channels
for transaction processing. A major benefit of the Raft ordering service is that you can configure a channel to only use specific
ordering nodes from the ordering service. That's why the console includes an Advanced Channel creation option to select a
subset of ordering nodes to include in the channel consenter set, where each ordering node that you select will contain a copy of
the channel ledger. Therefore, it is possible to restrict the channel ledger locations to only nodes that reside in country.

Figure 6. Org C and Org D create a Channel Y using ordering nodes only located in Germany. All data is stored in the
country on Ledger Y.
In Figure 6, the ordering nodes that participate in the Raft ordering service are spread across the two countries. Two ordering
nodes are located in the United States, and three ordering nodes are in Germany for a total of five ordering nodes. When Channel
X is created, all five ordering nodes are included in the consenter set, which wouldnot meet a data residency requirement as the
ledger data is spread across both countries. Channel Y however only includes the three ordering nodes that reside in Germany,
which guarantees that all ledger data for this channel stays in country. A minimum of three ordering nodes is recommended
because this configuration allows for one node to go down and two nodes to be available to maintain "quorum", the minimum
number of nodes that must be available (out of the total number) for the ordering service to process transactions. A more robust
configuration would be to include five ordering nodes in Germany for Channel Y, which means that two nodes could go down
without losing quorum.
The easiest way to achieve this configuration is to spread the ordering nodes across Kubernetes clusters in different regions, a
process that is described in the Setting up multiregion High Availability (HA) deployments for the ordering servicetutorial.
Considerations around using the IBM Blockchain Platform console

When you create an IBM Blockchain Platform service instance in IBM Cloud, you need to link the service instance to your
Kubernetes cluster on IBM Cloud. No ledger data is ever transmitted to the blockchain service instance that is running in IBM
Cloud.
When you use your console to view the channel details, ledger data is visible in your browser. The ledger data is transmitted
directly from the Kubernetes cluster to your browser. It is not passed to the service instance running on IBM Cloud.
Therefore, to preserve data residency, the end user's browser and the Kubernetes cluster must reside in the same country.
Reference material
For a deeper understanding of the flow of data on the IBM Blockchain Platform network, refer to the Fabric documentation on
transaction flow.
You can get more information about Private data collections and Zero Knowledge Proof in the white paper about Private and
confidential transactions with Hyperledger Fabric.

FAQs
Hyperledger Fabric
What is the value of using IBM Blockchain Platform over native Hyperledger Fabric?
What version of Hyperledger Fabric is being used with IBM Blockchain Platform?
Can IBM Blockchain Platform components interoperate with Hyperledger Fabric components on the same network? And
vice versa? And what is the support policy for networks that include both IBM Blockchain Platform components and open
source components?
Planning for your network
Is IBM Blockchain Platform HIPAA ready?

What ports are used by the IBM Blockchain Platform?
How can I estimate the IBM Blockchain Platform sizing requirements for my development, test, and production
environments?
How does pricing work on IBM Blockchain Platform for IBM Cloud?
What are the limitations of the free IBM Blockchain Platform using the IBM Cloud Kubernetes Service free cluster?
What regions or locations are available for the IBM Blockchain Platform for IBM Cloud?
What persistent file storage does IBM Blockchain Platform for IBM Cloud use by default?
Do I need multizone region storage for IBM Blockchain Platform nodes?
Deploying the platform or upgrading
What versions of Red Hat OpenShift are supported?

Is there a trial option available for using a Red Hat OpenShift cluster on IBM Cloud?
Is it possible to deploy blockchain nodes to multiple clouds from a single blockchain console?
How can I find what version of the IBM Blockchain Platform that I am running?
How do I get the latest Fabric version and Fabric functionalities on my IBM Blockchain Platform network?
I am currently using Hyperledger Fabric v1.4 and want to move to IBM Blockchain Platform for IBM Cloud or Multicloud.
Can I continue to use Raft?
Can I migrate the blockchain components on my IBM Kubernetes service cluster to a Red Hat OpenShift cluster in IBM
Cloud?
What happens when I delete my IBM Blockchain Platform service?
Can I use my existing Kubernetes cluster on IBM Cloud?
Blockchain components
What database do the peers use for their ledger?

What types of off-chain databases are supported with the IBM Blockchain Platform?
If service discovery is on, will an endorsement request be routed to any peer on the network?
Do ordering service Raft nodes use Transport Layer Security (TLS) for communication?
How can I back up and restore components and networks?
What benefits are available with the new smart contract lifecycle available on nodes and channels running on Fabric v2.x?
How can I check and interpret the status of my components through the Kubernetes command line?
Certificates
Do you support using certificates from non-IBM Certificate Authorities (CAs)?

What is the recommended way to manage private keys?
Can I integrate my corporate LDAP server with the Certificate Authority (CA) in the IBM Blockchain Platform?
What is the process for rotating certificates on a periodic basis?
Developing applications and smart contracts
What languages are supported for smart contracts?

What version of the IBM Blockchain Platform works with the Ansible collection?
How do I get support for running the IBM Blockchain Platform Ansible playbook?
Can the IBM Blockchain Platform monitor the health of a client application?
Monitoring your network
Where does IBM store the customer's logs and how long does IBM keep the audit logs for the blockchain platform
service?
Do we have access to logging services and what logs are available to me?
Where can I see the price breakdown for IBM Cloud Kubernetes Service, Storage, and Blockchain in my monthly invoice?
Is there a best practice for monitoring my blockchain resources?
Hyperledger Fabric is a powerful, versatile, pluggable, open source, distributed ledger technology capable of addressing a wide
variety of use cases across many industries. IBM Blockchain Platform is IBM's commercial distribution of Hyperledger Fabric. A
key benefit of the platform is that IBM tests the open source code for security vulnerabilities daily and provides 24x7x365
support with SLAs appropriate for production environments. The platform is the commercial distribution of Hyperledger Fabric
and includes integrated tools that provide end to end features for developers and network operators to develop, test, operate,
monitor, and govern Fabric components by using an intuitive console UI. Quickly deploy an instance and use the streamlined
console UI to build a network, easily deploy smart contracts, govern your components, and govern your channel. Interested in
APIs? See the IBM Blockchain Platform API reference. With the IBM Blockchain Platform, it is easy to extend a basic network,
work with multicloud solutions, and receive IBM worldwide support when needed. Finally, the IBM Blockchain Platform provides
additional security benefits that are essential for running an enterprise-grade production network.
IBM Blockchain Platform for IBM Cloud uses Hyperledger Fabric v1.4.12 and v2.2.5.
Can IBM Blockchain Platform components interoperate with Hyperledger Fabric

components on the same network? And vice versa? And what is the support policy
for networks that include both IBM Blockchain Platform components and open
source components?
Yes. Hyperledger Fabric networks consist of many distributed members owning one or more nodes. There are multiple
deployment options:
IBM Blockchain Platform for IBM Cloud with console

IBM Blockchain Platform v2.x (Full Platform)
IBM Blockchain Images
Open source Hyperledger Fabric images or a non-IBM product
Containers deployed from any of the above sources can be connected on a single channel and transact. You can join IBM
Blockchain Platform peers to any network running Hyperledger Fabric components. Similarly, you can invite Fabric peers to join
channels hosted on an ordering service deployed on the IBM Blockchain Platform. Note that you will need to use Hyperledger
Fabric APIs or the CLI. For more information about what is supported, see Support for IBM Blockchain Platform. For instructions
on how to configure interoperability see Connect the IBM Blockchain Platform to Hyperledger Fabric components.

Because HIPAA readiness is only relevant when platform components process Personal Health Information (PHI) or Personally
Identifiable Information (PII), the IBM Blockchain Platform does not need to be HIPAA ready. Customers should not store PHI or
PII on the ledger since it is immutable and therefore cannot be deleted. Instead, the recommendation is to store all PHI or PII

off ledger in another database and simply reference it from the ledger.
The IBM Blockchain platform gives customers total control over their deployments, certificates, and private keys. The console
simplifies and accelerates the process of deploying components into a Kubernetes cluster on IBM Cloud that is managed and
controlled by the customer. As a reminder, because the customer owns the storage that is mounted to the containers, IBM does
not have access to or control over any of the data that the customer chooses to store in their ledger.

See the port information in the Security topic that addresses this for the console and the customer Kubernetes cluster.
How can I estimate the IBM Blockchain Platform sizing requirements for my
development, test, and production environments?
After you understand how many CAs, peers, and ordering nodes are required, you can examine the default resource allocations
table for your nodes to get an approximate estimate of the CPUs (VPCs) required for your network. If you are purchasing IBM
Blockchain Platform on IBM Cloud, you can estimate your cost through this method, but you also have the ability to scale
dynamically if more sources are needed.
How does pricing work on the IBM Blockchain Platform for IBM Cloud?
IBM Blockchain Platform for IBM Cloud is priced based on the VPCs that you allocate to your blockchain nodes on the IBM
Kubernetes Service. For more information, see Pricing for IBM Blockchain Platform for IBM Cloud.
What are the limitations of the free IBM Blockchain Platform using the IBM Cloud
Kubernetes Service free cluster?
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. Read more about the limitations of free clusters.
IBM Cloud will delete your Kubernetes cluster after 30 days.
Only one blockchain console can be connected to a free cluster at a time.
You cannot migrate any nodes or data from a free cluster to a paid cluster.
The following capabilities are only available on a paid cluster:
Customizing resource allocation for a node during or after deployment.

Using a Hardware Security Module (HSM) to secure the private key for a node.
Configuring a Certificate Authority (CA) for high availability by using a PostgreSQL database and replica sets.
Selecting a specific Kubernetes zone when deploying a node.
Overriding node configuration during or after deployment by using the console or APIs.
Adding or removing ordering nodes to an ordering service. The free offering only supports a single node Raft ordering
service.
See Find out how to preview the platform free for 30 daysfor more information on how to get started.
What regions or locations are available for the IBM Blockchain Platform for IBM
Cloud?
The available regions for IBM Blockchain Platform are listed in IBM Blockchain Platform locations. Note that you must create a
Kubernetes cluster on IBM Cloud in the same region as the blockchain service to recognize the cluster. Additional regions will be
available soon.
What persistent file storage does IBM Blockchain Platform for IBM Cloud use by

default?
By default IBM Blockchain Platform for IBM Cloud uses Classic file storage. You can find more information on the IBM Cloud File
storage page. For a complete list of storage options, see Persistent storage considerations

No. When the IBM Blockchain Platform is configured with a multizone cluster in IBM Cloud Kubernetes service, you can choose
which zone a particular component (peer or ordering node) is deployed to, or you can let the console decide. Then, when the
node is subsequently deployed, Kubernetes "pins" the associated pod to the chosen zone. Pinning means that Kubernetes will
not provision the pod in another zone in the event of a whole zone failure. And because the pods are pinned to specific zones,
there is no need to access the same storage from another zone. Therefore, MZR storage is not required for IBM Blockchain
Platform nodes.

Currently, IBM Blockchain Platform for IBM Cloud supports linking to Red Hat OpenShift Container Platform 4.5, 4.6 and 4.7
clusters.
A free 30 day trial is available in the Red Hat Marketplace.. See Deploy from Red Hat Marketplace to learn more.
Is it possible to deploy blockchain nodes to multiple clouds from a single

blockchain console?
You cannot currently deploy blockchain nodes to multiple hosted cloud providers. However, you can use your console to operate
a distributed multicloud network by importing nodes deployed by using consoles on other clouds.
View the Support page by clicking the question mark icon in the upper right corner of the page. The IBM Blockchain Platform
version is visible under the page heading.
How do I get the latest Fabric version and Fabric functionalities on my IBM
Blockchain Platform network?
Depending on the contents of a Fabric release and IBM Blockchain Platform, it might only be necessary to upgrade nodes to get
access to the latest features. However, often it is necessary to update channel configurations with the latest capabilities in order
to get access to the latest Fabric features. In these cases, it is important to upgrade components and channels in a particular
order:
1. Upgrade nodes to the latest Fabric versions. Note that nodes are always backward compatible with earlier versions and
earlier capabilities. For more information about upgrading nodes, see Upgrading to a new version of Fabric.
2. Update channels with any new channel capabilities. If you update capabilities to a capability level (such as 2.0) before
upgrading nodes to the Fabric version corresponding to a capability, the node may crash. For more information, see
Capabilities.
Tip: If you are moving from v1.4.x to v2.x, you may have to update your smart contracts to conform to new smart contract
lifecycle. For more information, see Upgrading to a new version of Fabric.
I am currently using Hyperledger Fabric v1.4.x and want to move to IBM Blockchain

Platform for IBM Cloud . Can I continue to use Raft?
Yes. The IBM Blockchain Platform for IBM Cloud uses Raft consensus. All of the applications and smart contracts that you are
using on Fabric v1.4.x are able to work on your IBM Blockchain Platform network. However, no mechanism exists to migrate your
ledger data from one network to another. Instead, you can reinstall your smart contract packages on your IBM Blockchain
Platform network. See also Can IBM Blockchain Platform components interoperate with Hyperledger Fabric components on the
same network?.
Can I migrate the blockchain components on my IBM Kubernetes service cluster to

a Red Hat OpenShift cluster in IBM Cloud?
No. There is currently no way to migrate existing components to a new Red Hat OpenShift cluster in IBM Cloud.

When you delete an IBM Blockchain Platform service instance, all of the blockchain CAs, peers, smart contract pods (if using
peers deployed with a Fabric 2.x image; smart contracts deployed on peers using a Fabric 1.4.x image are located inside the
peer container), and ordering nodes are deleted along with their associated storage. If you have exported any nodes to other
consoles, make sure to reach out to the administrators of those consoles to let them know that those nodes are no longer
functioning, because deleting them in your console does not automatically delete them in theirs.

Your existing Kubernetes cluster works with the IBM Blockchain Platform if it satisfies the following conditions:
It is running Kubernetes version v1.23 - v1.24.

There are enough available resources in the cluster.

You have the choice of either CouchDB or LevelDB when you configure your peer database. Because data is modeled differently
in a Couch database than in a Level database, the peers in a channel must all use the same database type. See LevelDB versus
CouchDB to decide what is best for your business needs.
What types of off-chain databases are supported with the IBM Blockchain
Platform?
As a best practice it is recommended that you do not query the entire blockchain ledger for the purpose of aggregation or
reporting. If you want to build a dashboard or collect large amounts of data as part of your application, you can query an off chain
database that replicates the data from your blockchain network. This allows you to understand the data on the blockchain
without degrading the performance of your network or disrupting transactions.
You can use block or smart contract events from your application to write transaction data to an off-chain database or analytics
engine. For each block received, the block listener application would iterate through the block transactions and build a data
store by using the key/value writes from each valid transaction's read-write set. The Peer channel-based event services provide
replayable events to ensure the integrity of downstream data stores. For an example of how you can use an event listener to
write data to an external database, see the Off chain data sample in the Fabric samples.
Blockchain solutions can use any RDBMS or NoSQL DB such as IBM Cloudant for offchain data storage. Hyperledger Fabric does
not govern, interact with, or manage off-chain databases. In most cases, the off-chain database is used for reference data and
non-transactional data. IBM has successfully built blockchain products and solution accelerators with Hyperledger Fabric and
NoSQL databases such as OrientDB.

If service discovery is on, will an endorsement request be routed to any peer on the
network?
It depends on whether your endorsement policy is set to "ANY", in which any peer can sign an endorsement request, or whether
the policy is bound directly to an organization's peers. The service discovery information provided by the peer supplies two
pieces of information, Layouts and EndorsersByGroup . With these two pieces of data, the SDK has the ability to send
requests to peers in different organizations that meet the endorsement policy requirements. The Node.js SDK provides default
code that uses the Layouts and EndorsersByGroup and sends the requests to the appropriate peers to meet the
endorsement policy requirements. This existing logic can be customized to meet the business needs.
Do ordering service Raft nodes use Transport Layer Security (TLS) for
communication?
Yes. The Raft ordering service nodes are configured to use TLS communication. TLS is embedded in the trust model of
Hyperledger Fabric. By default, server-side TLS is enabled for all communications using TLS certificates. TLS is used to encrypt
the communication between your nodes and as well as between your nodes and your applications. TLS prevents man-in-the-
middle and session hijacking attacks. All IBM Blockchain Platform components use TLS to communicate with each other.

As with anything that is deployed to a Kubernetes-based cluster, backups of components and networks in the IBM® Blockchain
Platform are a matter of backing up its persistent volumes. These volumes are where ledgers and other types of storage are
mounted so they can be used by nodes.
As a result, "backing up" a component or a network is the process of saving a copy of the relevant persistent volumes, while
"restoring" a component or network involves bringing up components and pointing them to these saved volumes. For more
information, check out Backing up and restoring components and networks.
What benefits are available with the new smart contract lifecycle available on
nodes and channels running on Fabric v2.x?
The new smart contract lifecycle allows channel members to collaborate in the decision making process about smart contracts
like never before. Where previously smart contracts were instantiated on a channel by a single channel member and other
organizations only had the ability to choose whether to install the smart contract, the new lifecycle allows organizations to
propose, approve, and commit smart contracts at an organizational level.
This separation of concerns opens exciting new opportunities for collaborating organizations. For example, different
organizations can install smart contracts on their peers that contain only the code relevant to their business role and make minor
updates to these smart contracts where necessary, without needing to seek new approvals from other organizations.
For a tutorial on how this process is handled by the console, check out Deploy a smart contract using Fabric v2.x.
For information about to take advantage of the new lifecycle when writing a smart contract, check out Writing powerful smart
contracts.
How can I check and interpret the status of my components through the
Kubernetes command line?
To check the status of your component, run the following command:
kubectl get <CUSTOM_RESOURCE_TYPE> <CUSTOM_RESOURCE_NAME> -n <NAMESPACE> -o yaml
Replace <CUSTOM_RESOURCE_TYPE> with the custom resource type of your component (ibpca, ibppeer, ibporderer, or

ibpconsole).
Replace <CUSTOM_RESOURCE_NAME> with the name of your component.
Replace <NAMESPACE> with the name of your IBM Support for Hyperledger Fabric deployment namespace or OpenShift
project.
The spec.status field will contain details of your component's status:
errorCode
lastHeartbeatTime: when the controller last reconciled the component
message: long explanation of the status type
reason: short explanation of the status
status: "true" or "false" based on if status is valid
version: the product (IBP) version of the component
versions: the operand version of the component
type: describes the current status of the component
Deploying: component pod(s) spinning up but not yet running and ready
Deployed: component pod(s) are running
Precreated: (specific to the Orderer) Orderer is waiting for the genesis block to be created
Error: component hit an error during reconcile, or a certificate has expired
Warning: one or more of the component's certificate will be expiring within 30 days (by default)
Initializing: component is being reconciled again due to spec updates in the pre-reconcile checks
Do you support using certificates from non-IBM Certificate Authorities?

Yes, you can bring your own certificates if they are issued by a CA that is X.509 compliant. The CA should sign by using ECDSA
and the defaults should be set to use P256 curve. See this topic about Using certificates from an external CA with your peer or
ordering node.

Because private keys are not stored by the platform, users are responsible for downloading and securing their private key.
Therefore, when a higher level of security is required for private keys, an HSM is recommended. An HSM is a hardware appliance
that performs cryptographic operations and provides the capability to ensure that the cryptographic keys never leave the HSM.
Hyperledger Fabric supports HSM devices that implement the PKCS #11 standard. PKCS #11 is a cryptographic standard for
secure operations, generation, and storage of keys. See Configuring a node to use a Hardware Security Module (HSM)to learn
more.
Can I integrate my corporate LDAP server with the Certificate Authority (CA) in the
IBM Blockchain Platform?
You cannot currently directly integrate your LDAP server with the CA. However, you can use an external mechanism to generate
X.509 certificates for the LDAP users. To use those certificates with a peer or ordering service, see these topics on Using certs
from an external CA for your peer or ordering service and Manually building an organization MSP.
Note: Also, you cannot configure the blockchain console login authentication to use an LDAP user registry at this time.

Similar to how passwords need to be regularly updated, identity certificates need to be renewed, a process also referred to as
"certificate rotation". The platform displays certificate expiration dates for components throughout the console. When a
certificate expires, transactions on the network will fail because the identity can no longer be trusted. It is your responsibility to
monitor those expiration dates and manage your certificate renewal accordingly. The process varies depending on the type of

certificate, when it was generated, and for organization admin certificates, whether Node OU support was enabled on the MSP
when the identity was enrolled. The platform attempts to renew the peer and ordering node enrollment certificates 30 days
before they expire. See Managing certificates to learn more about the types of certificates that you need to monitor and how to
renew them.

The IBM Blockchain Platform supports smart contracts that are written in Node.js, Golang (Go), JavaScript, and Java. The new
Hyperledger Fabric programming model currently supports JavaScript, TypeScript, Java, and Go. If you are interested in
preserving your existing application code, or by using Fabric SDKs for Go, you can still connect to your IBM Blockchain Platform
network by using the lower-level Fabric SDK APIs.
Versions 2.1.3 and 2.5.x of the IBM Blockchain Platform can be used with the Ansible collection to deploy a Hyperledger Fabric
network.
Ansible is an open source technology and this product is not officially supported by IBM. For support related to the usage of the
IBM Blockchain Platform and Ansible playbooks use the GitHub repository.
The IBM Blockchain Platform console does not monitor the health of blockchain client applications, but IBM Cloud does offer
tooling such as IBM Log Analysis and IBM Cloud Monitoring that can be used for their health monitoring.
Where does IBM store the customer's logs and how long does IBM keep the audit
logs for the blockchain platform service?
The logs are stored in the customer's Kubernetes cluster. IBM does not have access to the logs and it is up to the customer to
manage all of their log data including retention management.
With IBM Blockchain Platform, you can now directly access logs from your Kubernetes dashboard. It is recommend that you take
advantage of the IBM Log Analysis service that allows you to easily parse the logs in real time.
Where can I see the price breakdown for IBM Cloud Kubernetes Service, Storage,
and Blockchain in my monthly invoice?
Actual cost breakdowns are visible from your Invoices in the IBM Cloud Dashboard. For detailed steps, see the Billing section in
the Pricing topic.

You are responsible for the health monitoring and resource allocation of the blockchain nodes in your Kubernetes cluster. While
requests against the nodes are being actively processed, you should be monitoring for spikes in resource consumption to avoid
problems. IBM recommends that you configure IBM Cloud Monitoring and set up alerts to track when blockchain nodes are
reaching their limits. See the tutorial on IBM Cloud Monitoring for more details.
Tip: You should be aware that JavaScript and TypeScript smart contracts require more resources than contracts written

in Golang. Therefore, when you are allocating resources to your cluster, it is important to ensure adequate resources are
available to your smart contract pods when they are deployed on a channel and during transaction processing. The pods
containing the smart contracts will consume as much resources as they need to function.

Disclaimer
ATTENTION: You must review the following information before you use any IBM® Blockchain plans.
IBM support statement

IBM's long history of leadership in innovation continues with the IBM Blockchain Platform offerings on IBM Cloud. Blockchain is
a rapidly progressing technology that is projected to disrupt the financial industry, local and global supply chains, and logistical
support in any number of business spaces. Through various early adoption programs, IBM customers and business partners are
actively driving blockchain as an industrial solution. IBM Blockchain Platform for IBM Cloud is one such program. As with any
new technology, IBM Blockchain Platform for IBM Cloud users need to be aware of the potential for rapid and fundamental
change.
The architecture behind IBM Blockchain is the Linux Foundation's Hyperledger Fabric project. Each open-source community
contribution improves Hyperledger Fabric but can present adoption challenges. IBM cautions against defining or exchanging
financial assets directly on any Hyperledger Fabric blockchain network.
Note: IBM does not support networks that use Hyperledger Composer in production, including the Composer CLI,
JavaScript APIs, REST server, and Web Playground.
Open-source statement
IBM Blockchain offerings are built based on the Linux Foundation's Hyperledger Fabric stack. Hyperledger Project members,
including IBM, continue to contribute to various subprojects under the Hyperledger umbrella. All contributions are reviewed,
vetted, and tested by the community.
Chaincode support statement

The following coding practices are NOT supported on IBM Blockchain networks:
1. Using associative arrays with iteration (the order is randomized in Go).

2. Reading a list of items from a KVS table (the order isn't guaranteed).
3. Writing thread-unsafe chaincode (query and invoke might be called in parallel).
4. Substituting global memory or cache storage for ledger state variables in chaincode.
5. Accessing external services, such as databases, directly from chaincode.
6. Using libraries or global variables that could introduce non-determinism (such as using "random" or "time").
Lastly, it is not recommended to write non-deterministic chaincode, which introduces risk to data consistency and integrity. The
Hyperledger Fabric architecture is designed to counter against non-deterministic chaincode through a series of endorsement
and validation checks. However, you are still urged to code deterministic functions that are not reliant on non-static global
variables, such as time.

Getting started
Build a network
IBM® Blockchain Platform is a blockchain-as-a-service offering that enables you to develop, deploy, and operate blockchain
applications and networks. You can learn more about blockchain components and how they work together by visiting the
Blockchain component overview. This tutorial is the first part in the sample network tutorial series and describes how to use the
IBM Blockchain Platform console to build a fully functional network on Kubernetes cluster deployed into the cloud infrastructure
of your choice.
blockchain network.
If you have not already used the IBM Blockchain Platform console to deploy components to a Kubernetes cluster on IBM Cloud,
see Getting started with IBM Blockchain Platform for IBM Cloud. Note that the console itself does not reside in your cluster. It is
a tool that you can use to deploy components into your cluster.
Whether you deploy components to a paid or free Kubernetes cluster, pay close attention to the amount of available resources in
your cluster when you choose to deploy nodes and create channels. It is your responsibility to manage your Kubernetes cluster
and deploy additional resources when necessary. While components will successfully deploy to an IBM Cloud free cluster, the
more components you add, the slower your components will run. For more information about component sizings and how the
console interacts with your Kubernetes cluster on IBM Cloud, see Allocating resources.
Tip: If you are using a Kubernetes cluster on IBM Cloud, it is recommended that you provision at least a 4CPU x 16GB
RAM cluster to accommodate the components in this tutorial.
Sample network tutorial series

This three-part tutorial series guides you through the process of creating and interconnecting a relatively simple, multi-node
Hyperledger Fabric network by using the IBM Blockchain Platform console to deploy a network into your Kubernetes cluster and
deploy a smart contract.
Note that while this tutorial shows how this process works with a paid Kubernetes cluster on IBM Cloud, the same basic flow
applies to free clusters, albeit with a few limitations (for example, you cannot size or resize nodes in a free cluster).
Build a network tutorial This tutorial guides you through the process of hosting a network by creating two organizations,
one for your peer and another for your ordering service, and a channel. Use this tutorial if you want to form a blockchain
consortium by creating an ordering service and adding organizations.
Join a network tutorial guides you through the process of joining an existing network by creating a peer and joining it to an
existing channel. Use this tutorial if you either do not intend to host a network by creating an ordering service, or want to
learn the process for joining other networks.
Deploy a smart contract on the network using Fabric v2.x shows how to write a smart contract and deploy it on a network.
Looking for a way to script the deployment of your nodes? If you are already familiar with the manual process to deploy the
components with the console, you can check out the Ansible playbooks, a powerful tool for scripting the deployment of
components in your blockchain network.
The structure of this network

If you complete all the steps in the Build a network and Join a network tutorials, your network will resemble the one in the
illustration below:

Org1 CA
Org 1
Peer Org1 Org1 MSP definition

Ledger X
Ordering service CA
Ordering service nodes
Ordering service MSP definition

Channel 1
Org2 CA
Org 2
Peer Org2 Org2 MSP definition

Ledger X
Figure 1. Sample basic network structure
This configuration is sufficient both for testing applications and smart contracts and as a guide for building components and
joining production networks that will suit your own use case. The network contains the following components:
Two peer organizations: Org1 and Org2

The tutorial series describe how to create two peer organizations and two associated peers. Think of organizations on a
blockchain network to be like two different banks that need to transact with each other. We will create the definitions of
Org1 and Org2.
One ordering service organization: Ordering Service
Because we are building a distributed ledger, the peers and ordering service should be part of separate organizations.
Therefore, a separate organization is created for the ordering service. Among other things, an ordering service orders the
blocks of transactions that are sent to the peers to be written to their ledgers and become the blockchain. We will create
the definition of the Ordering Service organization.
Three Certificate Authorities (CAs): Org1 CA, Org2 CA, Ordering Service CA
A CA is the node that issues certificates to both the users and the nodes associated with an organization. Because it’s a
best practice to deploy one CA per organization, we will deploy three CAs in total: one for each peer organization and one
for the ordering service organization. These CAs will also create the definition of each organization, which is encapsulated
by a Membership Service Provider (MSP). A TLS CA is automatically deployed together with each organization CA and
provides the TLS certificates that are used for communication between nodes. For more information, see Using your TLS
CA.
One ordering service: Ordering Service While deployments running on a paid cluster have the option to deploy either a
single node ordering service or a crash fault tolerant five node ordering service, free clusters only have the option of
running a single node. The crash fault tolerant five node ordering service uses an implementation of the Raft protocol (for
more information about Raft, see The Ordering Service and is the deployment option this tutorial will feature. This
ordering service will add peer organizations to its "consortium", which is the list of peer organizations that can create
channels. Currently, only one ordering service organization per ordering service is supported, regardless of the number of
ordering nodes associated with that organization. This ordering service will add peer organizations to its "consortium",
which is the list of peer organizations that can create and join channels. If you want to create a channel that has
organizations deployed in different clusters, which is how most production networks will be structured, the ordering
service admin will need to import a peer organization that has been deployed in another console into their console. This
allows the peer organization to join the channel that is hosted on that ordering service.
Two peers: Peer Org1 and Peer Org2
The ledger, Ledger x in the illustration above, is maintained by distributed peers. These peers are deployed with Couch

DB) as the state database in a separate container associated with the peer. This database holds the current value of all
"state" (as represented by key-value pairs). For example, saying that Org1 (a value) is the current owner of a bank asset
(the key). The blockchain, the list of transactions, is stored locally on the peer.
One channel: channel1
Channels allow sets of organizations to transact without exposing their data to organizations that are not members of the
channel. Each channel has its own ledger, collectively managed by the peers joined to that channel. The tutorial creates
one channel that is joined by both organizations, and shows how to instantiate a smart contract on the channel that the
organizations can use to transact.
This configuration isn't mandatory. The IBM Blockchain Platform is highly customizable. If you have resources available in your
Kubernetes cluster, you can use the console to deploy components in an endless array of configurations. This tutorial provides
the steps that you need to build your own network, with references to topics that provide a deeper dive into the IBM Blockchain
Platform and the console.
Important: You can deploy multiple peers that belong to the same organization MSP and multiple orderers that belong to
a different organization MSP. But the console does not prevent you from configuring peers and ordering nodes that belong
to a single same organization MSP. While it might seem that a single organization MSP for all your nodes would greatly
simplify deployment of your network, this configuration is problematic. Because the process to renew certificates is
different for peer and ordering nodes, when the renewal process is attempted after the node certificates expire in one
year, certificate renewal will fail. For that reason, using the same MSP for your peers and ordering nodes is strongly
discouraged.
In this Build a network tutorial, we build only a portion of the network above, a simple network that can be used to host an
ordering service and a single peer organization and peer on a single channel. The following illustration shows the portion of the
network above that we will build:
Org1 CA
Org1
Org1 MSP
Peer Org1
Ledger definition
X
Ordering service CA
Ordering service nodes
Ordering service
Channel 1 MSP definition
Figure 2. Simple network structure
This configuration is useful for quickly getting started and testing a smart contract but is not very meaningful until you add other
organizations to transact with, creating a truly distributed network. Therefore, in the subsequent Join a network tutorial, we
show you how to create additional peer organizations and peers, and how to add a new organization to the channel.
Tip: Throughout this tutorial we supply recommended values for the fields in the console. This allows the names and
identities to be easier to recognize in the tabs and drop-down lists. These values are not mandatory, but you will find them
helpful, especially since you will have to remember certain values like IDs and secrets of registered users that you input in
previous steps. As these values are not stored in the console, if you forget them, you will have to register additional users

and start the process over again. We provide a table of the recommended values after each task and recommend that if
you do not use the recommended values that you record your values as you proceed through the tutorial.
Step one: Create a peer organization and a peer

For each organization that you want to create with the console, you should deploy at least one CA. A CA is the node that issues
certificates to all network participants (peers, ordering services, clients, admins, and so on). These identities, which include a
signing certificate and private key, allow network participants to communicate, authenticate, and ultimately transact. These CAs
will create all of the identities and certificates that belong to your organization, in addition to defining the organization itself. You
can then use those identities to deploy nodes, create admin identities, and submit transactions. For more information about your
CA and the identities that you will need to create, see Managing identities.
In this tutorial, we create two organizations, one which will own a peer and another which will own an ordering service. Each
organization needs a CA to issue its certificates, therefore we need to create two CAs. For the purpose of this tutorial, we will
create only one CA at a time.
Watch the following video to learn about the process to create the peer's organization and the peer (for video tutorials on how to
create an ordering service and a channel, see video series:
Video transcript
Creating your peer organization's CA
Important: Your CA issues the certificates and private keys for your organization's admins, client applications, and nodes.
These identities are not managed by IBM and the private keys are not stored in the console. They are only stored in your
browser local storage. Therefore, make sure to export your identities and the MSP of your organization. If you attempt to
access the console from a different machine or a different browser, you will need to import these identities and
organization definitions.
To create the CA that will issue certificates for your first organization, perform the following steps in your console:
1. Navigate to the Nodes tab on the left and click Add Certificate Authority. The side panels will allow you to customize the
CA that you want to create and the organization that this CA will issue keys for.
2. In this tutorial, we're creating nodes, as opposed to importing them, so make sure the option toCreate a Certificate
Authority is selected. Then click Next.
3. Use the side panel to give your CA a display name. Our recommended value for this CA is Org1 CA. Then give your CA
admin credentials by specifying a CA administrator enroll ID of admin and a secret of adminpw. Again, these are
recommended values.
4. The Advanced deployment options are only available in paid clusters and can be safely ignored for purposes of this
tutorial. For more information about these options, see the links below.

Database and replica sets (Creating an HA CA) This option is only available on paid clusters.
Hardware Security Module (HSM)
Deployment zone selection (Multizone HA) This option is only visible when your cluster is configured with multiple
zones.
Resource allocation
5. Review the Summary page, then click Add Certificate Authority. The Edit configuration JSON button allows you to
override configuration settings for the CA. For this tutorial, the default settings are sufficient. See Customizing a CA
configuration to learn more about the options that are available.
Task: Creating the peer organization CA
Create CA Org1 CA admin adminpw
Table 1. Creating the peer organization CA
After you deploy the CA, you need to associate an admin identity. This will allow you to operate your CA and use it to create your
organization MSP, register users, and your peer.
Advanced users may already have their own CA, and not want to create a new CA in the console. If your existing CA can issue
certificates in X.509 format, you can use certificates from your own external CA instead of creating a new CA here. The CA
should sign using ECDSA and the defaults should be set to use P256 curve. See this topic on Using certificates from an external
CA with your peer or ordering node for more information.
Associating the CA admin identity

Each CA node is created with a CA admin identity. You use the admin identity to register new users with your CA and generate
certificates. Before you can use the console to operate your CA, you need to associate the CA admin identity with the CA node
itself.
deployed (or when the CA is otherwise unavailable), the status indicator box in the CA tile is a flashing gray box. When the
CA is successfully deployed and is running, this box is green, indicating that it is "Running" and can be operated from the
console. Before proceeding with the steps below, you must wait until the CA status is "Running". If the gray box stops
blinking, you can try reloading the page in your browser to refresh the status.
1. Click the Org1 CA tile in the Nodes tab. Then click Associate identity on the CA overview panel.
2. On the side panel that opens, provide an Enroll ID of admin and an Enroll secret of adminpw. For the Identity display
name, you can use the default value of Org1 CA Admin.
After setting the CA admin identity, you will be able to see the table of registered users in the CA overview panel.
Enroll ID Org1 CA Admin admin adminpw
Table 2. Associate the CA admin identity

You can view the CA admin identity in your console Wallet by clicking on theWallet in the left navigation. Click the identity to
view the certificate and private key of the CA admin.
Identity Org1 CA Admin Org1 CA admin identity
Important: The identity is not stored in your console or managed by IBM. It is only stored in local browser storage. If you
change browsers, you will need to import this identity into your Wallet to be able to operate the CA. Click Export identity
to download the identity along with its certificate and private key.
Using your CA to register identities

Each node or application that you want to create needs a certificate and private key to participate in the blockchain network. You
also need to create admin identities for your nodes so that you can manage them from the console. We will use our peer
organization CA to register two identities:
An organization admin: This identity allows you to operate nodes using the platform console.
A peer identity: This is the identity of the peer itself. Whenever a peer performs an action (for example, endorsing a
transaction) it will sign using its certificate.
Once you have associated the CA admin, you can use the CA tile to create these identities by completing the following steps:
1. Click the Org1 CA tile and ensure the admin identity that you created for the CA is visible in the table. Then click the
Register user button.
2. First we'll register the organization admin, which we can do by giving anEnroll ID of org1admin and a secret of
org1adminpw. Then set the Type for this identity as admin. You can ignore the Maximum enrollments field. If you want to
learn more about enrollments, see Registering identities. Click Next.
3. This tutorial does not configure attributes on identities, see Registering identities if you want to learn more. Click Register
user.
4. After the organization admin has been registered, repeat this same process for the identity of the peer (also using the
Org1 CA). For the peer identity, give an enroll ID ofpeer1 and a secret of peer1pw. This is a node identity, so select peer
as the Type. You can ignore the Maximum enrollments field and, on the next panel, do not assign anyAttributes, as
before.
Authority.
Note: Registering these identities with the CA is only the first step in creating an identity. You will not be able to use these
identities until they have been enrolled. Enrollment is the process that generates the certificate and private key for the
registered user. For the org1admin identity, this will happen during the creation of the MSP, which we will see in the next
step. In the case of the peer1 identity, it happens during the creation of the peer.
Task: Register users
Create CA CA admin admin adminpw client

Register users Org1 admin org1admin org1adminpw admin
Peer identity peer1 peer1pw peer
Table 4. Using your CA to register users
Creating the peer organization MSP definition

Now that we have created the peer's CA and used it toregister identities for the Org1 admin and for the Org1 peer, we need to
create a formal definition of the peer's organization, which is known as an MSP. Note that many peers can belong to an
organization. You do not need to create a new organization every time you create a peer. Because this is the first time that we
go through the tutorial, we will create the MSP definition for this organization. During the process of creating the MSP, we will
enroll the org1admin identity and add it to our Wallet.
2. On the first panel, enter Org1 MSP as the organization MSP display name and org1msp and as the MSP ID. If you plan to
specify an MSP other than org1msp, make sure to review the guidelines for MSP names in the tooltip. Click Next.
3. On the Root Certificate Authority details panel, specify the CA you used to register the identities for this organization. If
this is your first time through this tutorial, you should only see one: Org1 CA. The CA root certificate and TLS CA root
certificate are displayed. Click Next.
4. On the Admin certificates panel, select the enroll ID you created for your organization admin from the drop-down list,
org1admin, and enter its associated secret, org1adminpw. Then, give this identity a display name, Org1 MSP Admin . Note:
the default display name for this identity is the name of your MSP and the word "Admin". If you select a different name for
your MSP, that will be reflected in the default.
5. Click the Generate button to enroll this identity as the admin of your organization and export the identity to the Wallet,
where it will be used when creating the peer and creating channels.
6. Click Export to export the admin certificates to your file system. As we said above, this identity is not stored in your
console or managed by IBM. It is only stored in local browser storage. If you change browsers, you will need to import this
identity into your Wallet to be able to administer the peer. Click Next.
Exporting your organization admin identity is important because you are responsible for managing and securing these
certificates. If you switch browsers, you will need to import this admin identity otherwise you will not be able to operate
Org1.
7. On the Review MSP information panel, make sure you have entered the correct information. When you are satisfied, click
Create MSP definition.
8. After the MSP has been created, click on the tile representing it. Thendownload the MSP to your local filesystem. You will
need to send this MSP to all of the organizations in the channels you join.
Task: Create the peer organization MSP

Create Organization Org1 MSP org1msp
Root CA Org1 CA
Org Admin Cert org1admin org1adminpw
Identity Org1 MSP Admin
Table 5. Create the peer organization MSP definition
After you have created the MSP, you should be able to see the peer organization admin in your consoleWallet.

Identity Org1 CA Admin Org1 admin identity
Identity Org1 MSP Admin Org1 MSP admin identity
For more information about MSPs, see managing organizations.
Creating a peer
After you have created the Org1 CA, used it to register Org1 identities, and created the Org1 MSP, you're ready to create a peer
for Org1.
What role do peers play?

It's important to remember that organizations themselves do not maintain ledgers. Peers do. Organizations also use peers to
sign transaction proposals and approve channel configuration updates. Because having at least two peers per organization on a
channel makes them highly available, having three peers per organization joined to a channel is considered a best practice for
production level implementations because it ensures high availability even while a peer is down for maintenance. In this tutorial
though, we'll only show the process for creating a single peer. You can replicate the process to suit your own business needs.
From a resource allocation perspective, it is possible to join the same peers to multiple channels. The design of the peer ensures
that the data from one channel cannot pass to another through the peer. However, because the peer will store a separate ledger
for each channel, it is necessary to ensure that the peer has enough processing power and storage to handle the transaction and
data load.
Deploying your peer

Use your console to perform the following steps:
1. From the Nodes tab, click Add peer.

2. Make sure the option to Create a peer is selected. Then click Next.
3. Give your peer a Display name of Peer Org1.
State database
Multizone Kubernetes cluster (Multizone HA) This option is only visible when your cluster is configured for multizone
support.
Use your own CA certificate and private key
Resource allocation
5. Click Next.
6. On the Enter peer information page:
Select Org1 CA, as this is the CA you used to register the peer identity.
Select the Enroll ID for the peer identity that you created for your peer from the drop-down list,peer1, and enter its
associated secret, peer1pw.
Then, select Org1 MSP from the drop-down list
The TLS Certificate Signing Request (CSR) hostname is an option available to advanced users who want to specify
a custom domain name that can be used to address the peer endpoint. Custom domain names are not a part of this
tutorial, so leave the TLS CSR hostname blank for now.
In the Fabric version drop-down list, the best practice is to select thelatest available version, as it will contain the
latest bug fixes. It might also be necessary to select the latest version in order to have access to the latest features.

Note that if you select any version higher than v2.0, no smart contract container will be deployed along with your
peer. Instead, each smart contract will be deployed into its own pod when it is deployed on the channel or invoked
for the first time. Golang smart contracts that are currently running on a Fabric v1.4 peer need to be upgraded if you
plan to run them on a Fabric v2.x peer. See this topic on vendoring the shim for more information.
Click Next.
7. The last side panel asks you to Associate an identity to make it the admin of your peer. For the purpose of this tutorial,
make your organization admin, Org1 MSP Admin , the admin of your peer as well. It is possible to register and enroll a
different identity with the Org1 CA and make that identity the admin of your peer, but this tutorial uses theOrg1 MSP
Admin identity.
8. Review the summary and click Add peer. The Edit configuration JSON button allows you to override configuration
settings for the peer. For this tutorial, the default settings are sufficient. See Customizing a peer configuration to learn
more about the options that are available.
Task: Deploying a peer

Create Peer Peer Org1 org1msp
CA Org1 CA
Peer Identity peer1 peer1pw
Administrator certificate org1msp
Associate identity Org1 MSP Admin
Table 7. Deploying a peer
Tip: In a production scenario, it is recommended that each organization deploy three peers to each channel. These can
be the same three peers joined to different channels or different peers. It is up to the organization. This is to allow one
peer to go down (for example, during a maintenance cycle) and still maintain highly available peers. To deploy more than
one peer for an organization, use the same CA you used to register your first peer identity. In this tutorial, that would be
Org1 CA . Then, register a new peer identity using a distinct enroll ID and secret. For example, org1secondpeer and
org1secondpeerpw . Then, when creating the peer, give this enroll ID and secret. As this peer is still associated with
Org1, choose Org1 CA , Org1 MSP , and Org1 MSP Admin from the drop-down lists. You may choose to give this new
peer a different admin, which can be registered and enrolled with Org1 CA , but this optional. This tutorial series will only
show the process for creating a single peer for each peer organization.
Step two: Create the ordering service

In other distributed blockchains, such as Ethereum and Bitcoin, there is no central authority that orders transactions and sends
them out to peers. Hyperledger Fabric, the blockchain that the IBM Blockchain Platform is based on, works differently. It
features a node, or a cluster of nodes, called an ordering service.
The ordering service is a key component in a network because it performs a few essential functions:
It literally orders the blocks of transactions that are sent to the peers to be written to their ledgers. This process is called
"ordering".
On orderers with a system channel, it maintains the consortium, the list of peer organizations permitted to create
channels, resides.
It enforces the policies decided by the consortium or the channel administrators. These policies dictate everything from
who gets to read or write to a channel, to who can create or modify a channel. For example, when a network participant
asks to modify a channel or consortium policy, the ordering service processes the request to see if the participant has the
proper administrative rights for that configuration update, validates it against the existing configuration, generates a new

configuration, and relays it to the peers.
For more information about ordering services and the role they play in networks based on Hyperledger Fabric, see The Ordering
Service.
In a paid cluster, you have the option between creating a one node ordering service (sufficient for testing purposes) and a crash
fault tolerant ordering service featuring five nodes tied to a single organization. In a free cluster, you will only be able to create a
single node ordering service. In this tutorial, we will show the one node ordering service.
However, just as with the peer, before we can create an ordering service, we need to create a CA to supply the identities and the
MSP of our ordering service organization.
Watch the following video to learn about the process to create the ordering service's organization and the ordering service (for
video tutorials on how how to create a peer and a channel, see video series:
Video transcript
Ordering in the console

The production level ordering service available is a crash fault tolerant (CFT) ordering service based on an implementation of Raft
protocol in etcd . Raft follows a “leader and follower” model, where a leader node is selected (per channel) and its decisions are
replicated by the followers. Its design allows different organizations to contribute nodes to a distributed ordering service. For
more information about Raft, see The Ordering Service.
Currently, the only crash fault tolerant configuration of ordering nodes currently available is five nodes. While it is possible to
create a crash fault tolerant ordering service with as little as three nodes, this configuration incurs risk. If a node goes down, for
example during a maintenance cycle, only two nodes would be left. If another node was lost during this cycle for any reason,
only one node would left. In that state, a one node ordering service when you started with three, you would no longer have a
majority of nodes available, also known as a "quorum". Without a quorum, no transactions can be pushed and the channel stops
functioning.
With five nodes, you can lose two nodes and still maintain a quorum, meaning that you can undergo a maintenance cycle while
maintaining high availability. As a result, paid clusters will only have the choice between one node and five nodes. Production
networks should choose the five node option, as a one node ordering service is, by definition, not crash fault tolerant.
The ordering service can be run by either one organization (as might be the case in founder-led networks or in cases where the
consortium chooses an independent neutral entity to run all of the ordering nodes), or by multiple organizations which may or
may not contribute a node. Similarly, channel members can decide how many ordering nodes they want to service a channel.
Two organizations might decide to create a channel only using ordering nodes they own.
In this tutorial, we will create a one node ordering service managed by a single organization. If you want to add additional nodes
to this deployment, see Adding and removing ordering service nodes.

Creating your ordering service organization CA
The process for creating a CA for an ordering service is identical to creating it for a peer.
1. Navigate to the Nodes tab and click Add Certificate Authority.

2. In this tutorial, we're creating nodes, as opposed to importing them, so make sure the option toCreate a Certificate
Authority is selected. Then click Next
3. Give this CA a unique display name, Ordering Service CA . You're free to reuse the CA administrator enroll ID of admin
and a secret of adminpw. As this is a different CA, this identity is distinct from the CA admin identity for created for the
Org1 CA, even though the ID and secret are identical.
Multizone Kubernetes cluster (Multizone HA) This option is only visible when your cluster is configured with multiple
zones.
Resource allocation
5. Review the Summary page, then click Add Certificate Authority.
As with the peer, advanced users may already have their own CA and not want to create a new CA using the console. If your
existing CA can issue certificates in X.509 format, you can use certificates from your own external CA instead of creating new
certificates here. See this topic on Using certificates from an external CA with your peer or ordering node.

As you did for your peer organization, you need to associate the CA admin identity of the ordering organization and import the
identity into the console Wallet.
deployed (or when the CA is otherwise unavailable), the box in the tile for the CA will be gray box. When the CA has
successfully deployed and is running, this box will be green, indicating that it is "Running" and can be operated from the
1. Click the Ordering Service CA tile in the Nodes tab. Then click Associate identity on the CA overview panel.
name, you can use the default value of Ordering Service CA Admin .

Enroll ID Ordering Service CA Admin admin adminpw
Table 8. Associate CA admin identity
You should be able to see the CA admin in your Wallet. As we said above, the identity is not stored in your console or managed
by IBM. It is only stored in local browser storage. If you change browsers, you will need to import this identity into your console
Wallet to be able to operate the CA. Click the CA admin and then click Export identity to download the certificate and private
key.

Identity Org1 MSP Admin Org1 admin identity
Identity Ordering Service CA Admin Ordering Service CA admin identity
Using your CA to register ordering service node and ordering service admin identities
As we did with the peer, we need to register two identities with our ordering service CA. After selecting your CA, you will need to
register an admin for our ordering service organization and an identity for the ordering service itself.
After you have associated the CA admin, you can use the CA tile to create these identities by completing the following steps:
1. Click the Ordering Service CA tile in the Nodes tab and ensure the admin identity that you created for the CA is visible
in the table. Then click the Register user button.
2. First we'll register the organization admin, which we can do by giving anEnroll ID of OSadmin and a secret of OSadminpw.
Then set the Type for this identity as admin. You can ignore the Maximum enrollments field. If you want to learn more
about enrollments, see Registering identities. Click Next.
user.
4. After the organization admin has been registered, repeat this same process for the identity of the ordering service (also
using the Ordering Service CA ). For the ordering service node identities, give an enroll ID ofOS1 and a secret of OS1pw.
This is a node identity, so select orderer as the Type. You can ignore the Maximum enrollments field and, on the next
panel, do not assign any Attributes, as before.

Create CA Ordering Service CA admin adminpw client
Register users Ordering Service admin OSadmin OSadminpw admin
Ordering Service node identity OS1 OS1pw orderer
Table 10. Create a CA and register users
For the purpose of this tutorial, we are only creating one node identity. This identity will be used by the one node that we will
deploy to create the ordering service. While you would not want to do this in a multi-organizational ordering service, it is
acceptable given that all of the ordering nodes are owned by the same organization.
Creating the ordering service organization MSP definition

Create your ordering service organization MSP definition and specify the admin identity for the organization. After we have
registered the ordering service admin and ordering service users, we need to create the MSP ID and enroll the OSadmin user
that we registered as the admin of our organization.
2. Enter Ordering Service MSP as the organization MSP display name and osmsp and as the MSP ID. If you want to specify
your own MSP ID in this field, make sure to review the instructions in the tool tip.
3. Under Root Certificate Authority details, specify the CA you used to register the identities in the previous step,Ordering

Service CA.
4. The Enroll ID and Enroll secret fields below this will auto populate with the enroll ID of your CA admin:admin. However,
using this identity would give your organization the same admin identity as your CA, which for security reasons is not
recommended. Instead, select the enroll ID you created for your organization admin from the drop-down list, OSadmin,
and enter its associated secret, OSadminpw. Then, give this identity a display name, Ordering Service MSP Admin . Note:
5. Click the Generate button to enroll this identity as the admin of your organization and export the identity to the Wallet.
identity into your Wallet to be able to administer the peer.
certificates. If you export the ordering service and the ordering service MSP definition, they can be imported into another
console where another operator can create new channels on the ordering service or join peers to the channel.
7. Click Create MSP definition.

Create Organization Ordering Service MSP osmsp
Root CA Ordering Service CA
Org Admin Cert OSadmin OSadminpw
Identity Ordering Service MSP Admin
After you have created the MSP, you should be able to see the ordering service organization admin in yourWallet, which can be
accessed by clicking on the Wallet in the left navigation.

Identity Org1 MSP Admin Org1 admin identity
Identity Ordering Service CA Admin Ordering Service CA admin identity
Identity Ordering Service MSP Admin Ordering Service admin identity
Table 12. Check your wallet
Deploy the ordering nodes

Perform the following steps from your console:

1. From the Nodes tab, click Add ordering service.
2. Make sure the option to Create an ordering service is selected. Then click Next.
3. Give your ordering service a Display name of Ordering Service
4. If in a paid cluster, choose whether you want your ordering service to have one node (sufficient for testing) or five nodes
(good for production). Choose One ordering node for this tutorial.
5. Now choose the Without a system channel option. An orderer without the system channel will use the latest Fabric
features to manage channels and is the preferred way. The legacy configuration, with-a-system channel can still be
selected if you prefer the old way.
6. For the purpose of this tutorial, do not choose any of theAdvanced deployment options (only available in paid clusters).
For more information about these options, see the links below.
Multizone Kubernetes cluster (Multizone HA) This option is only visible when your cluster is configured with multiple
zones.
Resource allocation
7. Click Next.
8. On the next step, the Add ordering service page
Select Ordering Service CA as your CA.
Then, select the enroll ID for the node identity that you created for your ordering service from the drop-down list,
OS1.
Enter the associated secret, OS1pw.
Select your MSP, Ordering Service MSP from the drop-down list.
When you created the CA, a TLS CA was automatically created alongside it. The TLS CA is used to create certificates
for the secure communication layer for nodes. The TLS Certificate Signing Request (CSR) hostname is an option
available to advanced users who want to specify a custom domain name that can be used to address the ordering
service endpoint. Custom domain names are not a part of this tutorial, so leave the TLS CSR hostname blank for
now.
In the Fabric version drop down list, the best practice is to select thelatest available version, as it will contain the
Click Next.
9. The Associate identity step allows you to choose an admin for your ordering service. SelectOrdering Service MSP
Admin as before and click Next.
10. Review the Summary page and click Add ordering service. The Edit configuration JSON button allows you to override
configuration settings for the ordering service. For this tutorial, the default settings are sufficient. See Customizing an
ordering service configuration to learn more about the options that are available.

Create ordering service Ordering Service osmsp
CA Ordering Service CA
Ordering Service Identity OS1 OS1pw
Administrator certificate Ordering Service MSP
Associate identity Ordering Service MSP Admin
After the ordering service has been created, you are able to see it on theNodes panel.
Step three: Join the consortium hosted by the ordering service

As we noted earlier, a peer organization must be known to the ordering service before it can create a channel or be joined to a
channel when the channel is created. This act of being "known" to the ordering service is also known as "joining the consortium",
the list of organizations known to the ordering service. This is because channels are, at a technical level, messaging paths
between peers through the ordering service. Just as a peer can be joined to multiple channels without information passing from
one channel to another, so too can an ordering service have multiple channels running through it without exposing data to
organizations on other channels.
Because only ordering service admins can add peer organizations to the consortium, you will either need tobe the ordering
service admin or send MSP information to the ordering service admin.
Watch the following video to learn how to add a peer organization to the consortium, create the channel, and join a peer to the
channel. For video tutorials on how how to create a peer and an ordering service, see video series:
Video transcript
Add the organization to the consortium

After the Ordering service tile has the green status indicator you can proceed with the following steps. Because you created the
ordering service admin using the console, this process is relatively straightforward:

2. Scroll down to the ordering service you created and click the tile to open it.
3. Under Consortium Members, click Add organization.
4. From the drop-down list, select Org1 MSP, as this is the MSP that represents the peer's organization:Org1.
5. Click Add organization.
When this process is complete, it is possible for Org1 to create or join a channel hosted on your Ordering Service .
In this tutorial, we can easily access the Org1 MSP because both the peer organization and the ordering service organization
were created in the same console. In a production scenario, the MSP definitions of other organization would be created by
different network operators in their own cluster using their own IBM Blockchain console. In those cases, when the organization
wants to join your consortium, the organization MSP definition of the organization will need to be sent to your console in an out of
band operation. Additionally, you will need to export your ordering service and send it to them so they can import it into their
console and join a peer to the channel (if they are added to the consortium, they will also be able to create a new channel). This
process is described in the Join a network tutorial under Exporting your organization information.

Create a TLS identity
This step is needed on clusters that do not use a system channel. You can verify if a cluster does or does not use a system channel
by clicking the cluster's tile and looking near the Orderer Type text.
After you click the ordering cluster tile you may see a warning about missing a TLS identity. This identity is a different type than
we've used in the past and is only need for orderers that do not have a system channel. This identity is actually the same identity
the orderer is using when it enrolls on startup against the TLS CA. To get this identity:
1. From the Nodes tab, select the CA tile that this orderer cluster used (during create)
2. Find the row for the identity this orderer used and click the dot dot dot
3. On the enroll wizard select the TLS CA in the CA drop down (its important to select the TLS CA)
4. Type the enroll secret that was used earlier when creating the orderer
5. Follow any other directions in the enroll wizard and click submit
6. If you browse back to the nodes page and select the Orderer Cluster tile the TLS identity error should be gone
Step four: Create a channel
Important: In this tutorial, we will presume that users will not be attempting to edit any of the advanced options available
when creating a channel. For information about editing advanced options both before and after a channel has been
created, as well as more information about standard options, see Advanced channel deployment and management. Note
that to use the new 2.x lifecycle, you might need to use the advanced Capabilities option to increase the application
capability to 2_0 . For more information, check out Capabilities.
Although the members of a network are usually related business entities that want to transact with each other, there might be
instances when subsets of the members want to transact without the knowledge of the others. This is possible by creating a
channel on which these transactions will take place. Channels replicate the structure of a blockchain network in that they
contain members, peers, an ordering service, a ledger, policies, and smart contracts. But by restricting the membership, and
even the knowledge of the channel, to particular subsets of the network membership, channels ensure that network members
can leverage the overall structure of the network while maintaining privacy, where needed.
To join a peer from Org1 to a channel, Org1 must first be added to the consortium. After which, it can create a channel and join
a peer to it. If the organization is not a member of the consortium at channel creation time, it is possible to create the channel
and add the organization later by clicking the Settings button on the page of the relevant channel and editing the channel.
Important: After the channel has been created, subsequent organizations do not have to join the consortium before
being joined to a channel by the channel administrators through a channel configuration update. However, these
organizations will only be able to create their own channels if they are added to the consortium first.
For more information about channels and how to use them, see the Hyperledger Fabric documentation.
Watch Video 3 above to learn about the process to create channel and join your peer to the channel.
Creating a channel: channel1

Because the console uses peers to gather information about the channels that the peers belong to,unless an organization has
joined a peer to a channel, it cannot interact with the channel.
When you have created your CAs, identities, MSPs, ordering service, a peer, and have added your peer organization to the
consortium, navigate to the Channels tab in the left navigation. This is where channel creation and management are handled.
When you first navigate to this tab, it will be empty except for the Create channel and Join channel buttons. This is because you

haven't created a channel and joined a peer to it yet.
Creating the channel

1. Navigate to the Channels tab.

2. Click Create channel. The create channel panel will open. From here, you will perform all of the steps to create your
channel.
3. On the Prerequisites panel, you can decide whether or not you want to specify anyAdvanced channel configuration
options. For more information about these options, see Advanced channel deployment and management. For the
purposes of this tutorial, we'll assume you don't want to specify any advanced channel configuration options, so click Next.
4. On the Channel details page, give your channel a name and specify the ordering service the channel will be hosted on. In
this tutorial, our channel is called channel1 while the ordering service is called Ordering Service. Note: you will not be
able to change the channel name or the ordering service it is hosted on later. Click Next.
5. On the Organizations page, select the organizations that will be part of this channel. As we have only created one
organization, this will be Org1 MSP (org1msp). After clicking Add, you can assign the organization a role on the channel.
Because each channel must have at least one operator, make Org1 MSP (org1msp) an Operator.
6. Next, choose a Channel update policy for the channel. This is the policy that will dictate how many organizations will have
to approve updates to the channel configuration. Because this tutorial only involves creating a single organization, this
policy should be 1 out of 1 . As you add organizations to the channel, you should change this policy to reflect the needs
of your use case. A sensible standard in a five organization channel is to use a majority of organizations. For example, 3
out of 5.
7. If the ordering service is not using a system channel follow step A, else step B.
A. On the Orderer organizations page, choose the Ordering Service (osmsp) option from the drop-down. Then
select the Administrator checkbox. The orgs selected in this step will be able edit orderer configuration settings,
(such as block size, timeouts, consenters, etc) for the channel.
B. On the Channel creator organization page, pick the channel's creator. Because the console allows multiple
organizations to be owned by a single user, it is necessary to specify which organization is creating the channel.
Because this tutorial is limited to the creation of a single organization, choose Org1 MSP (org1msp) from the drop-
down list. Likewise, choose Org1 MSP Admin as the identity submitting the channel creation request.
8. On the Review channel information page, make sure you have entered the correct values in the correct fields. If a
required field is missing, you will see an error notification relating to the field or value that must be corrected. When you
are ready, click Create channel.
If the ordering service has a system channel you will be taken back to theChannels tab and you can see a pending
tile of the channel that you just created (under the Peer channels section).
If the ordering service does not have a system channel you will be taken to the wizard to join orderer nodes. Select
the orderer Ordering Service (osmsp) and click Join channel. You will now be taken back to the Channels tab.
Task: Create a channel

Field Name
Channel name channel1
Ordering Service Ordering Service
Organizations Org1 MSP
Channel update policy 1 out of 1
Access control list None
Channel creator MSP Org1 MSP
Table 14. Create a channel

The next step is to join a peer to this channel.
Step five: Join your peer to the channel

We are almost done. Joining the peer to the channel is the last step in setting up the basic infrastructure for your network. If you
are not already there, navigate to the Channels tab in the left navigation.
1. Click the pending tile for channel1 to launch the side panel.
2. Select which peers you want to join to the channel. For purposes of this tutorial, click the box next toPeer Org1.
3. Leave the checkbox for Make anchor peer selected. It is a best practice for each organization to have at least one anchor
peer on each channel, as anchor peers bootstrap the inter-organizational communication that enables features like
Private Data and Service Discovery to work. While it is only necessary to have one anchor peer on each channel, it does
not hurt to make all peers anchor peers. The only downside will be a short-term increase in the stress on your
communication layer when new organizations join their peers to the channel, as these peers are designed to contact every
anchor peer in every organization to find out about the peers belonging to that organization. Note that you can also make a
peer an anchor peer later through the Channels tab.
4. Click Join channel.
Important: In this tutorial, we are only creating and joining a single peer to the channel. As a result, you don't have to
worry about a conflict between the database type used by your peer (which in this tutorial is CouchDB) and any other
peers on the channel. However, in a production scenario, a best practice will be to ensure that the peer you are joining to
this channel uses the same database type as other peers on the channel. For more information, see LevelDB vs CouchDB.
Next steps
After you have created and joined your peer to a channel, you have a basic, though fully functional, blockchain network. Use the
following steps to deploy a smart contract and begin submitting transactions:
Deploy a smart contract on your network using Fabric v2.x using the console.
After your smart contract has been installed, proposed, approved, and then committed, you can submit transactions using
your client application.
You can also create another peer organization by using the Join a network tutorial. You can add the second organization to your
channel to simulate a distributed network, with two peers that share a single channel ledger.
Join a network
IBM® Blockchain Platform is a blockchain-as-a-service offering that enables you to develop, deploy, and operate blockchain
applications and networks. You can learn more about blockchain components and how they work together by visiting the
Blockchain component overview. This tutorial is the second part in the sample network tutorial series and describes how to
create nodes in the IBM Blockchain Platform console and connect them to a blockchain consortium hosted in another cluster.
blockchain network.
If you have not already used the IBM Blockchain Platform console to deploy components to a Kubernetes cluster on IBM Cloud,
see Getting started with IBM Blockchain Platform for IBM Cloud. Note that the console itself does not reside in your cluster. It is
a tool that you can use to deploy components into your cluster.
Whether you deploy components to a paid or free Kubernetes cluster, pay close attention to the resources at your disposal when
you choose to deploy nodes and create channels. It is your responsibility to manage your Kubernetes cluster and deploy
additional resources if necessary. While components will successfully deploy to an IBM Cloud free cluster, the more components

you add, the slower your components will run. For more information about component sizings and how the console interacts
with your Kubernetes cluster on IBM Cloud, see Allocating resources.

You are currently on the second part of our three-part tutorial series. This tutorial guides you through the process of using the
console to create and join a peer node to an existing IBM Blockchain Platform network. Note that while this tutorial shows how
this process works with a paid Kubernetes cluster on IBM Cloud, the same basic flow applies to free clusters, albeit with a few
limitations (for example, you cannot size or resize nodes in a free cluster).
Build a network tutorial guides you through the process of hosting a network by creating an ordering service and a peer.
Join a network tutorial (Current tutorial) Guides you through the process of joining an existing network by creating a peer
and joining it to a channel.
Deploy a smart contract using Fabric v2.x provides information on how to write a smart contract and deploy it on your
network.
You can use the steps in these tutorials to build a network with multiple organizations in one cluster for the purposes of
development and testing. Use the Build a network tutorial if you want to form a blockchain consortium by creating an ordering
service and adding organizations. Use the Join a network tutorial to connect a peer to the network. Following the tutorials with
different consortium members allows you to create a truly distributed blockchain network.
Looking for a way to script the deployment of your nodes? If you are already familiar with the manual process to deploy the
components with the console, you can check out the Ansible playbooks, a powerful tool for scripting the deployment of
components in your blockchain network.
This tutorial is meant to show how to join a peer to anexisting network. It presumes that an ordering service has already been
created using another IBM Blockchain Platform console (it is possible to join peers created in the IBM Blockchain Platform to
any network running Hyperledger Fabric based components using the Fabric APIs or the CLI, but we will not show that process
here). If you don't have an existing network to join, visit the Build a network tutorial to learn how to create one. The Join a
network tutorial takes you through the steps to create the following Org2 blockchain components, highlighted in the blue box:
Org1 CA
Org1
Org1 MSP
Peer Org1
Ledger definition
X
Orderer CA
Orderer Org
Orderer Orderer MSP

Channel1 definition
Org2 CA
Org2
Org2 MSP
Peer Org2 definition
Ledger
X
Figure 1. Join network structure
Perform the steps in the Join a network tutorial to create the following components and complete the following actions:
One peer organization Org2

Create the Org2 Membership Services Provider (MSP) definition which defines the organization Org2.
One peer Peer Org2

The ledger, Ledger x in the illustration above, is maintained by distributed peers. The peer is deployed with Couch DB as
the state database.
One Certificate Authority (CA) Org2 CA A CA is the node that issues certificates to all organization admins as well as to
nodes associated with an organization. We will create one CA for the peer organization Org2.
Joining one channel The tutorial describes how to join the channel that was created by the Build a network tutorial.
Tip: Throughout this tutorial we supply recommended values for some of the fields in the console. This allows the names
and identities to be easier to recognize in the tabs and drop-down lists. These values are not mandatory, but you will find
them helpful, especially since you will have to remember certain values, especially the IDs and secrets of registered
users, you input at a previous step. If you forget these values, you will have to register additional users for your admins
and components. We provide a table of the recommended values after each task and recommend that if you do not use
sample values that you record the values you do use somewhere as you proceed through the tutorial.

For each organization that you want to create with the console, you should deploy at least one CA. A CA is the node that issues
certificates to all network participants (peers, ordering services, clients, admins, and so on). These certificates, which include a
signing certificate and private key, allow network participants to communicate, authenticate, and ultimately transact. These CAs
will create all of the identities and certificates that belong to your organization, in addition to defining the organization itself. You
can then use those identities to deploy nodes, create admin identities, and submit transactions. For more information about your
CA and the identities that you will need to create, see Managing identities.
In this tutorial, we will create one organization. Therefore, we will need to createone CA.
Creating your peer organization CA
Important: Your CA issues the certificates and private keys for your organization's admins, client applications, and nodes.
These identities are not managed by IBM and the keys are not stored in the console. They are only stored in your browser
local storage. Therefore, make sure to export your identities and the MSP of your organization. If you attempt to access
the console from a different machine or a different browser, you will need to import these identities and organization
definitions.
1. Navigate to the Nodes tab on the left and click Add Certificate Authority. The side panels will allow you to customize the
CA that you want to create and the organization that this CA will issue keys for.
2. In this tutorial, we're creating nodes, so make sure the option to Create a Certificate Authority is selected. Then click
Next.
3. Use the side panel to give your CA a display name. Our recommended value for this CA is Org2 CA. Then give your CA
admin credentials by specifying a CA administrator enroll ID of admin and a secret of adminpw.
Deployment zone selection (Multizone HA) This option is only visible when your cluster is configured with multiple
zones.
Resource allocation
5. Review the Summary page, then click Add Certificate Authority. The Edit configuration JSON button allows you to
override configuration settings for the CA. For this tutorial, the default settings are sufficient. See Customizing a CA
configuration to learn more about the options that are available.
Task: Creating the peer organization CA

Create CA Org2 CA admin adminpw
Table 1. Creating the peer organization CA
After you deploy the CA, you will use it when you create your organization MSP, register users, and to create your entry point to a
network, the peer.
Advanced users may already have their own CA, and not want to create a new CA in the console. If your existing CA can issue
certificates in X.509 format, you can use certificates from your own third-party CA instead of creating new certificates here. The
CA should sign using ECDSA and the defaults should be set to use P256 curve. See this topic on Using certificates from an
external CA with your peer or ordering node for more information.

Each CA is created with a CA admin identity. You can use the admin to register new users with your CA and generate certificates.
Before you can use the console to operate your CA, you need to associate the CA admin identity with the CA node itself.
deployed (or when the CA is otherwise unavailable), the box in the tile for the CA will be gray box. When the CA has
successfully deployed and is running, this box will be green, indicating that it is "Running" and can be operated from the
Once the CA is running, as indicated by the green box in the tile, complete the following steps:
1. Click the Org2 CA tile in the Nodes tab. Then click Associate identity on the CA overview panel.
name, you can use the default value of Org2 CA Admin.
After setting the CA admin identity, you will be able to see the table of registered users in the CA overview panel.
Enroll ID Org2 CA Admin admin adminpw
Table 2. Associate the CA admin identity
You can view the CA admin identity in your console wallet by clicking on theWallet in the left navigation. Click the identity to
view the certificate and private key of the CA admin. The identity is not stored in your console or managed by IBM. It is only
stored in local browser storage. If you change browsers, you will need to import this identity into your Wallet to be able to
operate the CA. Click Export identity to download the certificate and private key.

Each node or application that you want to create needs certificates and private keys to participate in the blockchain network. You
also need to create admin identities for these nodes so that you can manage them from the console. We will create one CA and
use it to create two identities:
An organization admin: This identity allows you to operate nodes using the platform console.
A peer identity: This is the identity of the peer itself. Whenever a peer performs an action (for example, endorsing a
transaction) it will sign using its certificate.
Once you have associated the CA admin, you can use the CA tile to create these identities by completing the following steps:
1. Click the Org2 CA tile and ensure the admin identity that you created for the CA is visible in the table. Then click the
Register user button.
2. First we'll register the organization admin, which we can do by giving anEnroll ID of org2admin and a secret of
org2adminpw. Then set the Type for this identity as admin. You can ignore the Maximum enrollments field. If you want to
learn more about enrollments, see Registering identities. Click Next.
user.
4. After the organization admin has been registered, repeat this same process for the identity of the peer (also using the
Org2 CA). For the peer identity, give an enroll ID ofpeer2 and a secret of peer2pw. This is a node identity, so select peer
as the Type. You can ignore the Maximum enrollments field and, on the next panel, do not assign anyAttributes, as
before.
Authority.
Note: Registering these identities with the CA is only the first step in creating an identity. You will not be able to use these
identities until they have been enrolled. For the org2admin identity, this will happen during the creation of the MSP,
which we will see in the next step. In the case of the peer2 identity, it happens during the creation of the peer.
Task: Register users
Create CA CA admin admin adminpw client
Register users Org2 MSP Admin org2admin org2adminpw admin
Peer identity peer2 peer2pw peer
Table 4. Using your CA to register user
Creating the peer organization MSP

Now that we have created the peer's CA and used it toregister our organization identities, we need to create a formal definition
of the peer's organization, which is known as the Membership Services Provider (MSP) definition. Many peers can belong to an
organization. You do not need to create a new organization every time you create a peer. Because this is the first time that we
go through the tutorial, we will create the MSP definition for this organization. During the process of creating the MSP, we are
going to generate certificates for the org2admin identity and add them to our Wallet.
2. On the first panel, enter Org2 MSP as the organization MSP display name and org2msp and as the MSP ID. If you plan to
specify an MSP other than org2msp, make sure to review the guidelines for MSP names in the tooltip. Click Next.

3. On the Root Certificate Authority details panel, specify the CA you used to register the identities for this organization. If
this is your first time through this tutorial, you should only see one: Org2 CA. The CA root certificate and TLS CA root
certificate are displayed. Click Next.
4. On the Admin certificates panel, select the enroll ID you created for your organization admin from the drop-down list,
org2admin, and enter its associated secret, org2adminpw. Then, give this identity a display name, Org2 MSP Admin . Note:
5. Click the Generate button to enroll this identity as the admin of your organization and export the identity to the Wallet,
where it will be used when creating the peer and creating channels.
identity into your Wallet to be able to administer the peer. Click Next.
certificates. If you switch browsers, you will need to import this admin identity otherwise you will not be able to operate
Org2.
7. On the Review MSP information panel, make sure you have entered the correct information. When you are satisfied, click
Create MSP definition.
Task: Create the peer organization MSP definition
Create Organization Org2 MSP org2msp
Root CA Org2 CA
Org Admin Cert org2admin org2adminpw
Table 5. Create the peer organization MSP definition
After you have created the MSP, you should be able to see the peer organization admin in yourWallet, which can be accessed by
clicking on the Wallet in the left navigation.
Identity Org2 MSP Admin Org2 identity
Creating a peer
After you have created a CA, used it to register identities, and created the peer organization MSP, you're ready to create a peer.
What role do peers play?

It's important to remember that organizations themselves do not maintain ledgers. Peers do. Organizations also use peers to
sign transaction proposals and approve channel configuration updates. Because having at least two peers on a channel makes
them highly available, having at least two peers joined to a channel is considered a best practice for production level
implementations. In this tutorial, we'll only show the process for creating a single peer.
From a resource allocation perspective, it is possible to join the same peers to multiple channels. The design of the peer ensures
that the data from one channel cannot pass to another through the peer. However, because the peer will store a separate ledger
for each channel, it is necessary to ensure that the peer has enough processing power and storage to handle the transaction and
data load.
Deploying your peer
Use your console to perform the following steps:
1. On the Nodes page, click Add peer.

2. Make sure the option to Create a peer is selected. Then click Next.
3. Give your peer a Display name of Peer Org2.
State database
Multizone Kubernetes cluster (Multizone HA) This option is only visible when your cluster is configured for multizone
support.
Resource allocation
5. Click Next.
6. On the Enter peer information page:
Select Org2 CA, as this is the CA you used to register the peer identity.
Select the Enroll ID for the peer identity that you created for your peer from the drop-down list,peer2, and enter its
associated secret, peer2pw.
Then, select Org2 MSP from the drop-down list
The TLS Certificate Signing Request (CSR) hostname is an option available to advanced users who want to specify
a custom domain name that can be used to address the peer endpoint. Custom domain names are not a part of this
tutorial, so leave the TLS CSR hostname blank for now.
In the Fabric version drop down list, the best practice is to select thelatest available version, as it will contain the
Note that if you select any version higher than v2.0, no smart contract container will be deployed along with your
peer. Instead, each smart contract will be deployed into its own pod when it is deployed on the channel or invoked
for the first time. Golang smart contracts that are currently running on a Fabric v1.4 peer need to be upgraded if you
plan to run them on a Fabric v2.x peer. See this topic on vendoring the shim for more information.
Click Next.
7. The last side panel asks you to Associate an identity to make it the admin of your peer. For the purpose of this tutorial,
make your organization admin, Org2 MSP Admin , the admin of your peer as well. It is possible to register and enroll a
different identity with the Org2 CA and make that identity the admin of your peer, but this tutorial uses theOrg2 MSP
Admin identity.
8. Review the summary and click Add peer. The Edit configuration JSON button allows you to override configuration
settings for the peer. For this tutorial, the default settings are sufficient. See Customizing a peer configuration to learn
more about the options that are available.
Task: Deploying a peer
Create Peer Peer Org2 org2msp

CA Org2 CA
Peer Identity peer2 peer2pw
Administrator certificate org2msp
Associate identity Org2 MSP Admin
Table 7. Deploying a peer
Tip: In a production scenario, it is recommended to deploy three peers to each channel. This is to allow one peer to go
down (for example, during a maintenance cycle) and still maintain highly available peers. To deploy more than one peer
for an organization, use the same CA you used to register your first peer identity. In this tutorial, that would be Org2 CA .
Then, register a new peer identity using a distinct enroll ID and secret. For example, org2secondpeer and
org2secondpeerpw . Then, when creating the peer, give this enroll ID and secret. As this peer is still associated with
Org2, choose Org2 CA , Org2 MSP , and Org2 MSP Admin from the drop-down lists. You may choose to give this new
peer a different admin, which can be registered and enrolled with Org2 CA , but this optional. This tutorial series will only
show the process for creating a single peer for each peer organization.
Step two: Add Org2 to an existing channel

In the Build a network tutorial, Org1 created a channel, channel1 , with itself as the only member. For Org2 to join this channel,
it must export its MSP to Org1:
1. Navigate to the Organizations tab. You can see the organizations available for export are listed under Available
organizations. Click the Export button inside the Org2 MSP organization tile to download the JSON configuration file that
represents the MSP of the peer organization.
2. Send this file to Org1 in an out of band operation.
Then Org1 must complete the following steps in its own console:
1. If the Org2 MSP was created by using a different console and sent out of band, it needs to be imported into the console
where the ordering service resides. If the Org2 MSP is created in the same console where the ordering service resides, you
can skip this step: Click the Organizations tab then Import MSP definition. Click Add file and browse to the Org2 MSP json
file that was sent out of band. Click Import MSP definition. The administrator identity for the MSP definition is not
required.
2. Navigate to the Channels tab, click channel1.
3. Click the Settings icon to update the channel and add the peer organization to the channel.
4. In the Channel updater MSP drop-down list (under the Organization updating channel heading), select Org1 MSP. In the
Identity drop-down list, ensure that Org1 MSP Admin is selected.
5. In the Organizations section, open the Select a channel member drop-down list and select the peer organization MSP,
Org2 MSP.
6. Click Add and then assign permissions for that organization. We recommend you make them an Operator so that Org2
can operate the channel (this will allow them to sign channel updates, for example).
7. Under Update policy, select 2 out of 2 , meaning both of the organizations need to approve updates to the channel.
At this point no further changes are required on the channel. In the left navigation, clickReview channel information. On the
Review channel information panel, you can see that there are now two organization members on the channel, org1msp and
org2msp . In addition the channel update policy has been changed to 2 out of 2 . When you are ready, click Update channel
to submit your changes.
Important: Org1 must also export its own MSP, Org1 MSP , and send it to Org2 in an out of band operation.All members
of a channel should have the MSPs of the other channel members.

At this point, Org2 is listed in the channel configuration and therefore technically part of the channel. However, more steps must
still be completed.
Export the ordering service and its MSP
Tip: This step can be performed either by Org1 or the ordering service admin.
If the ordering service and its MSP are not yet present on the file system of either Org1 or the ordering service, complete the
following steps to Export the ordering service before it can be imported by the peer organization:
1. Navigate to the ordering service inside the Nodes tab. Click the Export button beneath the ordering service name to
download a JSON configuration file.
2. Send this file to Org2 in an out of band operation. The peer organization administrator can then use the configuration file
to add the ordering service to the console.
Tip: The rest of the actions in this section and Step three need to be performed from the console where the Org2 MSP
was created.
Import the ordering service
Note: If the Org2 MSP was created in the same console as the ordering service, this step can be skipped.
Complete the following steps to import the ordering service into your console:
1. Navigate to the Nodes page and click Add ordering service.

2. Click the option to Import an existing ordering service.
3. Then click the Add file button to select the JSON that represents the ordering service.
4. Click Add ordering service.
Step three: Join your peer to the channel

Your peer can now be joined to channel1 .
1. If you are not already there, navigate to the Channels tab in the left navigation. There will not be any channel tiles visible
yet.
2. Click the Join channel button to launch the side panels.
3. Select Ordering Service and click Next.
4. Enter channel1 and click Next.
5. Select which peers you want to join the channel. For purposes of this tutorial, clickPeer Org2. Leave the tab for Make
anchor peer selected. It is a best practice for each organization to have at least one anchor peer on each channel, as
anchor peers bootstrap the inter-organizational communication that is necessary for Private Data and Service Discovery
to work. While it is only necessary to have one anchor peer on each channel, it does not hurt to make all peer anchor
peers. The only downside will be a short term increase in the stress on your communication layer when new organizations
join their peers to the channel, as these peers are designed to contact every anchor peer in every organization to find out
about the peers belonging to that organization. Note that you can also make a peer an anchor peer later through the
Channels tab.
6. Click Join channel.
Important: In these tutorials, we create all of our peers using default options, which means that every peer uses
CouchDB. As a result, you don't have to worry about a conflict between the database type used by your peer and any other
peers on the channel. However, in a production scenario, a best practice will be to ensure that the peer you are joining to
this channel uses the same database type as other peers on the channel. For more information, see LevelDB vs CouchDB.

Step four: Creating a channel
Note: In this tutorial, we will presume that users will not be attempting to edit any of the advanced options. For
information about editing advanced options both before and after a channel has been created, see Advanced channel
deployment and management.
Join the consortium hosted by the ordering service

A peer organization must be known to the ordering service before it can create a channel (this is also known as joining the
"consortium", the list of organizations known to the ordering service). This is because channels are, at a technical level,
messaging paths between peers through the ordering service. Just as a peer can be joined to multiple channels without
information passing from one channel to another, so too can an ordering service have multiple channels running through it
without exposing data to organizations on other channels.
Because only ordering service admins can add peer organizations to the consortium, you need to either:
Be the ordering service admin. In which case you can add the peer organization you created to the consortium directly.
Send MSP information to the ordering service admin, who will add your organization to their consortium.
In the next step, we will show how to add your peer organization to a consortium hosted by an ordering service in another IBM
Blockchain Platform service instance. The tutorial assumes that you have created the ordering service and can follow every step
yourself. If the ordering service was created in another console, ensure that the ordering service admin follows the steps marked
with the blue "tip" box at the top.
If you followed the Build a network tutorial or if your console already includes the ordering service, you can skip ahead to Add
the peer's organization to the ordering service. You can then continue with Step two: Add the peer's organization to an existing
channel.
Export your organization information

If the ordering service admin does not already have your MSP, export it and send it to them now.
Import the organization definition
Tip: This step needs to be completed by an ordering service admin.
Once the MSP representing Org2 has been received, an administrator of the ordering service must import the JSON file by
navigated to the Organizations tab, clicking the Import MSP definition button, and selecting the JSON file that represents the
Org2 MSP peer organization MSP definition.
Add Org2 MSP to the ordering service consortium
Tip: This step needs to be completed by an ordering service admin.
After the MSP representing Org2 has been imported, use these steps to add the peer organization to the consortium hosted by
the ordering service. Only ordering service admins, those who are listed under Ordering service administrators in the Details tab
of the ordering service, can add peer organizations to the consortium. You must have the ordering service organization admin
identity in your Wallet to perform this task.

2. Scroll down to the ordering service you want to use and click the tile to open it.

4. From the drop-down list, select Org2 MSP, as this is the MSP that represents Org2.
Once your organization is a member of the consortium, you have the ability create a new channel. First, you will need to import
the MSP definition of other channel members. Use the steps below to create a channel with two members: the Org1 that was
created in the Build a network tutorial and the Org2 that was created in the steps above.

Because the console uses peers to gather information about the channels that the peers belong to,unless an organization has
joined a peer to a channel, it cannot interact with the channel.
When you have created your CAs, identities, MSPs, ordering service, a peer, have added your peer organization to the
consortium, and have imported the MSPs of any organizations who will be joined to this channel, navigate to the Channels tab in
the left navigation. This is where channel creation and management are handled.
When you first navigate to this tab, it will be empty except for the Create channel and Join channel buttons. This is because you
haven't created a channel and joined a peer to it yet.
Creating the channel
1. Navigate to the Channels tab.

2. Click Create channel. The create channel panel will open. From here, you will perform all of the steps to create your
channel.
3. On the Prerequisites panel, you can decide whether or not you want to specify anyAdvanced channel configuration
options. See Advanced options to learn more. For the purposes of this tutorial, we'll assume you don't want to specify any
advanced channel configuration options, so click Next.
4. On the Channel details page, give you channel a name and specify the ordering service the channel will be hosted on. In
this tutorial, our channel is called channel2 while the ordering service is called Ordering Service.
5. On the Organizations page, select the organizations who will be part of this channel. Since we have two organizations,
select and add Org1 MSP (org1msp) and then Org2 MSP (org2msp). After clicking Add, you can assign an organization a
role on the channel. Because each channel must have at least one operator, make both organizations Operator.
6. Next, choose a Update policy for the channel. This is the policy that will dictate how many organizations will have to
approve updates to the channel configuration. As this channel includes two organizations, this policy should be 2 out of
2, meaning both organizations have to approve updates to the channel. As you add organizations to the channel, you
should change this policy to reflect the needs of your use case. A sensible standard is to use a majority of organizations.
For example, 3 out of 5 .
7. On the next page, select the Organization creating channel. Because the console allows multiple organizations to be
owned by a single user, it is necessary to specify which organization is creating the channel. Because this tutorial is limited
to the creation of a single organization, choose Org2 MSP (org2msp) from the drop-down list. Likewise, choose Org2 MSP
Admin as the identity submitting the channel creation request.
8. On the Review channel information page, make sure you have entered the correct values in the correct fields. If a
required field is missing, you will see an error notification relating to the field or value that must be corrected.
When you are ready, click Create channel. You will be taken back to the Channels tab and you can see a pending tile of the
channel that you just created.
Task: Create a channel
Field Name
Channel name channel2
Ordering Service Ordering Service

Organizations Org2 MSP
Channel update policy 2 out of 2
Access control list None
Channel creator MSP Org2 MSP
Table 8. Create a channel
The next step is to join a peer to this channel. Click the pending tile and select the organization peers to be added to the channel.
Next steps
After you have joined your peer to a channel, use the following steps to deploy a smart contract and begin submitting
transactions to the blockchain:
Deploy a smart contract on your network using Fabric v2.x using the console.
After you have installed and instantiated your smart contract, you can submit transactions using your client application.
The commercial paper sample can be used to deploy an example smart contract and submit transactions from sample
application code.
IBM Blockchain Platform getting started videos

You can watch the getting started video series to learn more about how to use IBM® Blockchain Platform.
Getting started with IBM Blockchain Platform 2.5.3

Watch the following video series to learn more about the IBM Blockchain Platform and how you can get started to build your
own network:
Deploy the console
Deploy a peer
Deploy an ordering service
Create and join a channel
Deploy a smart contract

A smart contract is the code, packaged as chaincode, that applications interact with to read and update data on the blockchain
ledger. A smart contract turns business logic into an executable program that is agreed to and verified by all members of a
blockchain network. This tutorial is the third part in the sample network tutorial series and describes how to deploy smart
contracts to start transactions in the blockchain network.
blockchain network. Additionally, application developers might be interested in the sections that reference how to create a
smart contract.

You are currently on the third part of our three-part tutorial series. This tutorial guides you through the process of using the

console to deploy a smart contract onto a channel in your IBM Blockchain Platform network.
Build a network tutorial guides you through the process of hosting a network by creating an orderer and peer.
Join a network tutorial guides you through the process of joining an existing network by creating a peer and joining it to a
channel.
Deploy a smart contract on the network (Current tutorial) Provides information on how to write a smart contract and
deploy it on your network.
development and testing. Use the Build a network tutorial if you want to form a blockchain consortium by creating an orderer
node and adding organizations. Use the Join a network tutorial to connect a peer to the network. Following the tutorials with
different consortium members helps you create a truly distributed blockchain network.
Select the tutorial that corresponds to your channel configuration:
* Channel application capabilities and peer Fabric images are 2.x

Channel application capabilities are 1.4 and peer Fabric images are 1.4 or 2.x
Important: * Fabric v2.0 introduced a new distributed process to manage the lifecycle of a smart contract that allows for
decentralizing the governance of smart contracts on a channel. Whenever possible, it is recommended that customers
should move to using the new smart contract lifecycle to avoid any interruption of service in later upgrades when Fabric
no longer supports the v1.4 process for installing and instantiating smart contracts.

A smart contract is the code, packaged as chaincode, that applications interact with to read and update data on the blockchain
ledger. A smart contract turns business logic into an executable program that is agreed to and verified by all members of a
blockchain network. This tutorial is the third part in the sample network tutorial series and describes how to deploy smart
contracts to start transactions in the blockchain network.
smart contract.

You are currently on the third part of our three-part tutorial series. This tutorial guides you through the process of using the
console to deploy a smart contract onto a channel in your IBM Blockchain Platform network.
Build a network tutorial guides you through the process of hosting a network by creating an orderer and peer.
Join a network tutorial guides you through the process of joining an existing network by creating a peer and joining it to a
channel.
Deploy a smart contract on the network (Current tutorial) Provides information on how to write a smart contract and
deploy it on your network.
development and testing. Use the Build a network tutorial if you want to form a blockchain consortium by creating an orderer
node and adding organizations. Use the Join a network tutorial to connect a peer to the network. Following the tutorials with
different consortium members helps you create a truly distributed blockchain network.
Select the tutorial that corresponds to your channel configuration:
* Channel application capabilities and peer Fabric images are 2.x

Channel application capabilities are 1.4 and peer Fabric images are 1.4 or 2.x

Important: * Fabric v2.0 introduced a new distributed process to manage the lifecycle of a smart contract that allows for
decentralizing the governance of smart contracts on a channel. Whenever possible, it is recommended that customers
should move to using the new smart contract lifecycle to avoid any interruption of service in later upgrades when Fabric
no longer supports the v1.4 process for installing and instantiating smart contracts.
Deploy a smart contract using Fabric v2.x

Using the Hyperledger Fabric v2.x chaincode lifecycle, learn how to create and package a smart contract and how to
propose the smart contract definition to channel members on a channel that runs application capability 2.x . Learn how
to install the smart contract package on peers that run a Fabric 2.x image. Finally, see how channel members can approve and
commit the smart contract definition to the channel.
Important: While the terms "smart contract" and "chaincode" are often used interchangeably, "smart contracts" refers to
the business logic that governs transactions and access to its data, while "chaincode" refers to the larger infrastructure of
packages and other code that encompasses a smart contract.
If you prefer to continue to use the legacy smart contract deployment process, see Deploy a smart contract using Fabric v1.4.
Instead of a single organization administrator making decisions for all organizations about when a smart contract is updated,
what it contains, and where it runs, Fabric v2.0 introduced a new distributed process to manage the lifecycle of a smart contract
that allows for decentralizing the governance of smart contracts on a channel. The process for installing, proposing, and
updating a smart contract is known as the "lifecycle" of a smart contract. This lifecycle is necessarily ongoing, as it encompasses
changes to the smart contract itself as well as updates to a channel, as for example when a new member starts using the smart
contract, and is managed through a combination of processes inside and outside the console.
Lifecycle process overview
Attention! The IBM Blockchain Platform Extension for VS Code (VS Code extension) referenced throughout the
documentation is an open-source project which is no longer active, and therefore not officially supported by IBM. Refer to
the alternatives to the VS Code extension.

Figure 1. Smart contract lifecycle
The diagram illustrates the smart contract lifecycle process. Org1 begins the process by packaging the smart contract using the
blockchain VS Code extension or the Fabric peer CLI. After packaging, all smart contract lifecycle management is performed
from the Channels tab in the console. Org1 proposes the smart contract definition to the channel and installs it on one or more
Org1 peers. The smart contract definition includes the definition name, version, endorsement policy, and optionally, private data
collections. As a proposer of the definition, Org1 attaches the smart contract package, which contains the agreed to business
logic that updates the ledger. The package can be shared with the channel members out of band, who can review the source
code. However, it's important to understand that channel members approve the smart contract definition, not the package.
Because Org1 is proposing the smart contract definition, their approval is automatically submitted with the proposal. The other
three organizations can approve or abstain. When channel members approve a smart contract definition, they are not required to
install the package on their peers. They have three options:
Simply approve the definition.

Approve the definition and install the package on one or more of their peers.
Approve the definition and upload their own package, as long as it does not change any agreed to business logic.
In the diagram, Org2 and Org4 approve the smart contract definition. Org3 abstains, perhaps because the owner of the Org3
admin identity is on vacation. After the approvals that are specified in the channel lifecycle endorsement policy are satisfied, any
channel member that has approved the definition can commit it to the channel (only one channel member needs to perform the
action). In this case, Org4 submits the commit transaction. It's important to note that Org3 can still come back later and approve
the definition and install the package on the Org3 peers.
For more information about advanced channel options, which includes setting the lifecycle policy for the channel and the default
endorsement policy that will be set for a smart contract if none is specified, check out the Advanced options section of our topic
on channels.
Before you begin

Ensure peer is running Fabric v2.x image
As a reminder, to leverage the smart contract lifecycle process, the peers on the channel must be running a Fabric v2.x image.
The Fabric level of a peer is visible in the console by clicking a peer node to open it.
Figure 1. How to find the Fabric version of the peer
If your peer is running a Fabric v1.4.x image, you cannot use this tutorial to manage your smart contract. Instead, see the
Deploy a smart contract using Fabric v1.4 tutorial for instructions on how to deploy the smart contract on the channel or
upgrade the peer to use a Fabric v2.x image.
Update MSPs in consortium to add organization-level endorsement policy

To use the 2.x smart contract lifecycle, an organization must have an endorsement policy defined. If any organization in the
consortium (the list of organizations maintained by the ordering service that are allowed to create channels) do not have an
endorsement policy defined, a warning message will appear on the Details page of the ordering service with a list of organization
MSPs that must be updated.
The best practice to add this endorsement policy to the MSP is to delete the MSP from the system channel and then re-add the
MSP. The console detects the fact that the MSP does not contain the endorsement policy and automatically adds it. Note that
this action can only be completed by an ordering service administrator. You do not need to delete and re-add the MSPs in the
configuration of any application channels that have already been created. For these MSPs, the endorsement policy is added as
part of the process of deploying the smart contract.
Create channel and join peers

Because the lifecycle of a smart contract begins by installing the smart contract on a peer that is joined to a channel, you need
to create a channel and include the organization members. The channel must be configured to run with the Fabric 2.0
application capability level. Second, you need to deploy at least one peer (that must be running the Fabric v2.x image) for your
organization and join it to the channel. If you haven't already created a channel and joined at least one peer to it, see the Build a
network tutorial for instructions.
Important: If you are creating a new channel, ensure that you select Advanced channel configuration so that you have
the opportunity to specify the Channel Application Capability 2.0.0 or higher.
Export and Import Membership Service Providers (MSPs)

A benefit of the decentralized nature of smart contract lifecycle governance is that channel members can agree upon which
organizations on the channel and how many of them are required to approve a smart contract definition before it can be
committed to a channel. This agreement is described in the channel "lifecycle endorsement policy" when the channel is created.
Because an approval notification is sent to each organization in the policy, the console requires the endpoint address of each

organization, which happens to be included in their MSP. Therefore, each organization that is specified in the lifecycle
endorsement policy must export their MSP and send it to the other members in the policy. And then each member must import
the MSP from each organization into their console. These import and exports steps should have already happened, before the
organization peers joined the channel. See Importing an MSP for more details.
Peer admin identity

Because only peer admin identities are allowed to install a smart contract on a peer, if you plan to propose a smart contract
definition, you need to have the peer admin identity in your console wallet. The peer admin identity is generated when the peer
organization MSP is created and it is associated with the peer node during node deployment. If you are unsure, open the peer
tile, and in the left column, view the name of the admin identity under Associated identity for peer. That is the identity that must
be in your wallet and is required when you propose a smart contract definition.
Limitations
Can I continue to use the Fabric SDK to deploy my smart contracts?

If your client applications are using the Fabric v1.4 SDK to deploy smart contracts, those functions will no longer work when the
peers are running on a channel with the Fabric 2.0 application capability enabled. In this case, you can only use the Fabric v1.4
or v2.x SDKs with the IBM Blockchain Platform to submit transactions or queries against smart contracts. The SDKs cannot be
used to submit administrative transactions such as installing a smart contract, proposing a smart contract definition,
approving it, or committing it to a channel. Instead, customers can use the console UI, the Fabric CLI, or Ansible playbooks to
perform these administrative tasks.
What happens to my existing smart contracts?

Although support for Fabric 2.0 networks was added to the platform, you can still run your existing smart contracts on your
peers that run a v1.4 image on a channel with an application capability level of 1.4 or lower. Should you later decide to upgrade
your peer to a v2.x image and update your channel application capability level to 2.0, you may need to update your existing
smart contract. However, after you upgrade your peer image to v2.x and channel application capability v2.x, there is no longer a
way to update the original smart contract. Instead, when an update is required, you need to repackage the smart contract in the
new .tar.gz or .tgz format using v2 of the VS Code extension and then propose the definition to the channel using the new
smart contract lifecycle process.
Review the following considerations:
Node
If your smart contract was written in Node, then you might need to update it. By default, a Fabric v1.4 peer will create a Node v8
runtime, and a Fabric v2.x peer creates a Node v12 runtime. In order for a smart contract to work with Node v12 runtime, the
fabric-contract-api and fabric-shim node modules must be at v1.4.5 or greater. If you are using a smart contract that
was originally written to work with Fabric 1.4, update the Node modules by running the following command before deploying the
smart contract on a Fabric v2.x peer. See Support and compatibility for fabric-chaincode-node for more information.
npm install --save fabric-contract-api@latest-1.4 fabric-shim@latest-1.4
Go
Because Fabric v2.x peers do not have a "shim" (the external dependencies that allowed smart contracts to run on earlier
versions of Fabric), you need to vendor the shim and then repackage any smart contracts written in Golang (Go) that use the Go
SDK. "Vendoring the shim" effectively means that you are copying the dependencies into your project. Without this vendoring
and repackaging, the Go smart contract cannot run on a peer using a Fabric 2.x image. If you are using the IBM Developer Tools
to develop and package your smart contract, the tooling performs the vendoring for you. This process is not required for smart

contracts that are written in Java or Node.js, nor for Go smart contracts that use the Go contract-api.
Java
The build.gradle file for the smart contract must be updated:
1. If the smart contract uses the shadowjar 2.x plugin, then it should be updated to version 5 by using the following code:
plugins {
id 'com.github.johnrengelman.shadow' version '5.1.0'
id 'java'
}
2. The repositories section of the file must contain the maven URL for jitpack , for example:
repositories {
...
maven {
url 'https://jitpack.io'
}
}
Init functions
If the smart contract was written using the low-level APIs provided by the Fabric Chaincode Shim API, your smart contract
needs to contain an Init function that is used to initialize the chaincode. This function is required by the smart contract
interface, but does not necessarily need to be invoked by your applications. Because you cannot use the console to deploy a
smart contract that contains an Init function, you need to move that initialization logic into the smart contract itself and call it
separately. For example, the smart contract can use a reserved key to check whether the smart contract has already been
initialized or not. If not, then call the initialization logic, otherwise proceed as usual. If your smart contract needs to include the
Init function, the only way to deploy it is by using the Fabric peer lifecycle chaincode install command or the IBM Blockchain
Platform collection for Ansible. You can also refer to the Fabric documentation for more details on how to use an Init function
with the Fabric chaincode lifecycle.
Repackage smart contract
After you have updated your smart contract, use v2 of the VS Code extension to repackage your smart contract.
Step one: Write and package your smart contract

The IBM Blockchain Platform console manages the deployment of smart contracts rather than development. If you are
interested in developing smart contracts, you can get started with tutorials provided by the Hyperledger Fabric community and
tooling provided by IBM.
To learn how smart contracts can be used to conduct transactions among multiple parties, see the Developing
applications topic in the Hyperledger Fabric documentation.
When you are ready to start building smart contracts, use the IBM Developer Tooling, by downloading the VS Code
extension locally. New to the VS Code extension? Check out Developing smart contracts with IBM Blockchain Platform
Developer Tools to get started using the extension to create smart contracts that run on the network and clients

applications to send transactions.
For a quick tutorial on developing smart contracts, see Develop a smart contract with the IBM Blockchain Platform VS
Code extension.
For guidance on how to leverage the smart contract lifecycle to satisfy a wider set of business use cases, see Writing
powerful smart contracts.
For a more in-depth end-to-end tutorial about using an application to interact with smart contracts, see Hyperledger
Fabric Commercial Paper tutorial.
To learn about how to incorporate access control mechanisms into your smart contract, see Writing Your First Chaincode.
When they are tested and ready to be deployed on the network, smart contracts must be packaged into a .tgz or tar.gz
format in order to be uploaded to the console. Because the smart contract packaging uses the tar format, organizations can
easily inspect their contents by using widely available tooling. When it is important to review the smart contract package before
approving the definition, the package can be shared out of band with organization members. There is no way to share the
package from the console. You can use either the IBM Developer Tooling or the peer lifecycle chaincode package CLI to
package your smart contract.
Tip: Smart contracts in .cds format cannot be used with the Fabric 2.0 lifecycle. They need to be repackaged into .tgz
format. See the VS Code tutorial for instructions on how to repackage your smart contract.
Vendoring smart contracts

If your smart contract uses the fabric-chaincode-go shim or the Go contract-api you need to repackage the smart contract
before it can be installed on a peer that is running a Fabric v2.x image.
Why is vendoring the shim required?
In Fabric v1.4.x, the Go chaincode shim and protocol buffers (protos) were included with the Fabric distribution and were
included in the Go chaincode runtime in the IBM Blockchain Platform. Starting with v2.0, Fabric now provides the chaincode
shim and protos as separate repositories that need to be imported or "vendored" in Go smart contracts before they can be
installed on a peer that runs a Fabric v2.x image. To vendor the shim for your Go smart contract, navigate to your smart contract
source folder and initialize the Go module by issuing the following command which creates a go.mod file:
go mod init
Add the required imports to go.mod by running the following command:
go test
The go.mod file will resemble:
$ module mysmartcontract
go 1.14
require (
github.com/hyperledger/fabric-chaincode-go v0.0.0-20200511190512-bcfeb58dd83a
github.com/hyperledger/fabric-protos-go v0.0.0-20200506201313-25f6564b9ac4
)
or if you are using the Go contract-api , it will resemble:
$ module github.com/hyperledger/fabric-samples/chaincode/fabcar/go
go 1.13
require github.com/hyperledger/fabric-contract-api-go v1.1.0

You can then get the necessary dependencies to install the Go smart contract on a 2.x peer by issuing the following command
that completes the vendoring of the smart contract:
go mod tidy
go mod vendor
See the Go documentation to learn more about what these commands do.
Package Construction
The following example shows the folder structure of a "marbles" smart contract that uses the fabric-chaincode-go shim before
the vendoring process:
$ ├── META-INF
│ └── statedb
│ └── couchdb
│ └── indexes
│ └── indexOwner.json
├── marbles_chaincode.go
└── util
└── util.go
And after the vendoring process, the structure is as follows:
$
├── META-INF
├── go.mod
├── go.sum
├── util
│ └── util.go
└── vendor
├── github.com
│ ├── golang
│ │ └── protobuf
│ └── hyperledger
│ ├── fabric-chaincode-go
│ └── fabric-protos-go
├── golang.org
├── google.golang.org
└── modules.txt
Note: The source directory must be the smart contract name which is "marbles" in this case. Therefore, the import for the
util package in the smart contract would be:
import "marbles/util"
After you have completed these steps, you need to repackage your smart contract using the process that is described in
Packaging smart contracts.
Tip: Fabric-contract-api and fabric-shim node modules must be at v1.4.5 or greater to work with Node version 12. If you
are using a smart contract that was originally written to work with Fabric 1.4, check the node modules before deploying
your smart contract on a peer that runs a Fabric v2.x image.
Versioning smart contract definition and packages

As a best practice, a smart contract package name should be of the format [SMART_CONTRACT_NAME]_[VERSION] where the
initial smart contract version would be 1.0.0 , for example: MySmartContract_1.0.0 . Before you package your smart
contract, you should consider this format for the name to allow for versioning of the package in the future. For more details,
review Versioning a smart contract.
Step two: Install and Propose smart contract

After packaging a smart contract, its lifecycle on the channel begins by installing the smart contract on your own organization
peers and proposing the smart contract definition to the other channel members. You install a smart contract package and
propose a smart contract definition.
All lifecycle actions are managed from the Channels tab in the console.
1. Navigate to the Channels tab, open the channel, and click Propose smart contract definition. This single action actually
performs two tasks. It installs a smart contract on one or more of your peers and proposes the smart contract definition to
the channel.
2. Because the console allows you to act as multiple organizations from a single console, you must first select the
organization that is proposing this smart contract definition and the associated peer admin identity. A peer admin identity
is required to install a smart contract. Not sure? Open the peer CA and verify that the identity associated with the peer has
the type admin in the list of CA users.
3. On the next panel, browse to your smart contract package and clickAdd file. You can install a new package or browse to
an existing package that was installed on another peer in your organization. Smart contract packages can also be installed
on a peer node directly by using the Install smart contract button. If you used that option, instead of clicking Add file,
click the Existing package tab and select the package that you installed on your peer.
4. On the Smart contract details panel you can specify a unique name and version to use for this smart contract definition.
The console extracts these values from the package name itself but you can override them and specify any values that
your organization prefers. Be careful how you name your proposal. If a proposal with the same name already exists on the
channel, this proposal replaces it.
5. On the Install smart contract panel, you can install the smart contract on all your peers on the channel or just a subset. In
a production network, for redundancy reasons, you should install the smart contract on at least two peers, or three when
you want to maintain redundancy but still allow for one peer to go down for maintenance. Since you are proposing the
smart contract, it must be installed on at least one peer.
6. On the Smart contract endorsement policy panel, you can designate how many organizations need to endorse a smart
contract transaction before it can be committed to the ledger. The default smart contract endorsement policy is inherited
from the application endorsement policy of the channel, but can be overridden here by selecting specific organizations
and the required number, or by pasting in your own policy JSON. Remember, this smart contract endorsement policy
becomes part of the proposal that must be agreed to by the other channel members before the smart contract can be
committed to the channel. The endorsement policy must follow the format that is specified in the Fabric documentation
endorsement policy syntax.
7. If your smart contract includes Fabric private data collections, you need to upload the associated collection configuration
JSON file on the Additional private data collection panel. Otherwise, you can skip this step. For more information, see
private data.
8. Your smart contract proposal definition is listed on the Summary panel. Everything that you selected on the previous
panels become part of the proposal definition. It also includes the list of organization members that will receive the
proposal notification. Once a proposal is created, the definition cannot be modified. Proposal definitions cannot be

modified after they are created. If, after creating the proposal you realize that changes are required to the definition, you
need to create a new proposal. However, you are permitted to update the package on the proposal.
9. When you are satisfied with the proposal, click Propose to install the smart contract on the selected peers and send an
approval notification to the channel members. When the proposal is successful, it is visible in the Channels tab under
Smart contract definitions with a status of Proposed on the tile. It is also visible to members of the channel lifecycle
endorsement policy under the console Notifications (bell) icon.
Tip: If other organizations will run the package on their peers, you need to share the name of the package with them out
of band, so they can select it and install it on their peers when they approve the smart contract definition. The smart
contract package name is included on the proposal Summary panel.
Step three: Approve smart contract definition

The decentralized governance of the smart contract lifecycle requires that the specified number of organizations in the channel
lifecycle endorsement policy approve the smart contract definition before it can be committed to a channel. All organizations
listed in the channel lifecycle endorsement policy receive a notification when a proposal definition is submitted to the channel.
They can access the proposal from the Notification (bell) icon in the console or simply open the Channels tab where they can
find the smart contract definition tile in the Proposed state. Clicking the tile or the notification opens the same approval panel.
Figure 2. Smart contract approval panel
Proposal originators can view the proposal using the same mechanisms. However, by virtue of submitting the proposal, their
approval is automatic.
Channel members approve the smart contract definition, not the smart contract package, which contains the business logic
that runs on a peer. A smart contract proposal contains the following information:
Smart contract definition name

Version
Smart contract endorsement policy
Private data collection JSON (optional)

The members, including the originator, cannot change the definition. They can simply approve it or choose not to approve it. If
the required approvals based on the channel lifecycle endorsement policy are not met, the smart contract cannot be committed
to the channel.
1. Click Begin approval process to get started.
2. Before you can approve a smart proposal, you are required to select your organization and the associatedpeer admin
identity that you want to use to approve or endorse the proposal.
3. Channel members can choose among these options:
Approve the definition, but do not install the package on any of their peers. Useful when the smart contract can
run on the channel but is not required for your organization.
Approve the definition and install the package on one or more peers in their organization.The proposal originator
needs to share the package file out of band with the channel members so they can upload it and install it on their
peers. Smart contract packages cannot be shared from the console.
Approve the definition but upload their own package and install it on one or more peers in their organization.
When an organization prefers to run their own version of the smart contract package on the channel (provided the
read/write set logic is the same), they can upload their own smart contract package file during the approval.
Approve the definition but select an existing package from another peer in their organization.When an
organization prefers to run their own version of the smart contract package on the channel, provided that the
read/write set logic is the same, and that package is already installed on another peer in their organization, they can
select the existing smart contract package during the approval.
If a member wants to reject the smart contract proposal, they should simply abstain from approving the
definition. Instead, they can create a new smart contract proposal with the definition they prefer and either upload
a new smart contract package or use the existing one from the original proposal. Note: The new proposal must use
a new smart contract definition name.
After you approve a smart contract proposal and while it is waiting for approvals from other members, you can still update the
package for your organization, or install it on additional peers if needed. Simply, reopen the proposal tile on the Channels tab
and click Update package details next to your organization to upload a new package. If you do upload a new package, when you
create the updated package, we recommend incrementing the third digit of the version on the package name to help you
differentiate the packages. For example, if the existing package is named MySmartContract@1.0.0.tar.gz , the new package
is named MySmartContract@1.0.1.tar.gz .
Note: The Begin approval process or Update package details buttons are not visible on the panel when the console user
does not have an identity in their wallet for a listed organization.
Step four: Commit smart contract definition

If you are familiar with the process that Fabric v1.4 used for deploying a smart contract, the commit step is similar to
instantiation , which makes the smart contract active on the channel so that peers can begin endorsing transactions.
When enough organizations have approved the smart contract definition according to the channel lifecycle endorsement policy,
the status of the definition on the tile changes to Ready to commit.

Figure 3. Smart contract definition ready to commit status
All organizations on the channel that received the approval notification can click the tile to see the organizations that have
approved the definition and begin the commit process or they can update the package that will run on their peers after the
definition is committed.
Tip: Unsure what version of the smart contract is currently running on your organization peers? From the Nodes tile, open
the peer and scroll down to the Installed smart contracts table to view the list of smart contracts installed on the peer.
Click Download from the action menu to inspect the smart contract version.
1. Click Begin commit process when you are ready to commit the definition to the channel. After enough approvals have
been satisfied according to the channel lifecycle endorsement policy, only one organization has to commit the definition to
the channel.
2. You are required to select your organization and the associated peer admin identity that you want to use to commit the
definition.
When the smart contract definition is successfully committed to the channel, the status on the tile changes toCommitted.
How do I?
Based on the preceding steps, the following table provides a summary of the lifecycle actions that are required depending on
your goal:
Task Instructions
Deploy and run You need to package the smart contract into .tgz or .tar.gz format and then propose it to the
a smart contract channel. As part of the proposal process you must install the package on at least one peer.
on a channel Organizations who are members of the lifecycle endorsement policy (specified when the channel is
created or updated), must approve the definition. After the channel members specified in the lifecycle
endorsement policy approve the definition, any of them can commit the definition, at which point the
smart contract can start to process transactions on the peers.
Install a smart If the smart contract has not yet been proposed to the channel, navigate to theChannels tab and click
contract on my Propose smart contract definition. See Install and propose a smart contract for more details.
peers
Otherwise, open the smart contract tile on the Channels tab. Next to your organization, click Begin
approval process or Update package details (if you have already approved the proposal) and either
upload a package or select an existing package to install, then select one or more peers to install it on.
Note: It is still possible to install a smart contract on a peer from the peer tile on the Nodes tab. But
this only installs the smart contract on the peer, it does not propose it to the channel.
Propose a new From the Channels tab, click Propose smart contract definition. As the proposal originator, you are
smart contract required to either, upload a new smart contract package and install it on at least one peer, or select an
definition existing package from one of your organization peers. Because you are proposing a new smart
contract, a smart contract proposal with the same definition name cannot already exist. If it does, it
will get replaced by this proposal.

Install a If there are no differences in the agreed to business logic in your smart contract package, you can use
different smart your own package instead. From the Channels tab, open the smart contract tile and click eitherBegin
contract approval process next to your organization. Click Add file to upload your own package or Existing
package than package to select a package that is already installed on a peer in your organization.
what is included
in the smart Note: If the smart contract business logic has changed, you need to submit a new proposal for
contract approval and attach the new smart contract package.
proposal
Update a smart I submitted the proposal, but need to update the smart contract package. If the agreed to business
contract logic has not changed, from the Channels tab, open the smart contract tile and click Update package
package after I details next to your organization. Click Add file to upload a new version of the smart contract.
submitted the
proposal
Approve a smart Open the smart contract tile on the Channels tab. Next to your organization, click Begin approval
contract process. You are required to select which admin identity from your organization will submit the
definition approval.
If you are ready to approve the smart contract but are not ready to install it on your peers at this time,
when prompted to upload or select an existing package, simply click No to skip this step. A package is
not required when you approve a smart contract definition.
Or, if you want to install the package that the proposal originator included, click Add file to upload the
smart contract package shared with you by the proposal originator out of band.
Lastly, you can install your own version of the smart contract, by clicking Add file to upload your own
package or Existing package if the package is already installed on another peer in your organization.
If you upload or select a new package, you can choose which peers to install it on.
Install the smart Forgot to install the package on a peer? Or perhaps you've added new peers? Open the smart
contract on contract tile on the Channels tab. Next to your organization, click Update package details. If you want
additional or to install the same package on the newly added peers, click Existing package and browse to the
newly added package that you want to install. Otherwise, you can click Add file to upload a new package. Then,
peers after I select which peers to install the package on.
approved it
Reject a smart Fabric does not include an option to reject a smart contract proposal. Rather, you can abstain from
contract approving, which can prevent the proposal from ever satisfying the lifecycle endorsement policy. Or,
proposal or you can make a new proposal with a new smart contract definition name, and include the terms that
definition you prefer.
Commit a smart After the proposal has reached the required number of approvals, the status of the proposal on the
contract Channels tab changes to Ready to commit. Any channel member can click the tile and then click
definition Commit to commit the definition to the channel. At that point, the associated smart contract can
begin accepting transactions on the peers.

Update a smart All updates to smart contract definitions have to be approved by channel members, according to the
contract channel lifecycle endorsement policy, before they can be committed to the channel. Changes that
definition that require approval include:
has been
committed to Updates to the agreed to business logic of the smart contract that require a new package.
the channel Updates to the smart contract endorsement policy.
Updates to a private data collection.
Tip: If no changes are made to the agreed to business logic, then updates to the smart contract
package do not require approval of channel members. See the next task,Update a smart contract
package after the definition is committed to the channel.
To update any of these elements, you have to create a new proposal in order for the update to be
approved. You can additionally update the smart contract package but it is not required, for example if
you only need to change the endorsement policy.
Important: If the proposal includes a smart contract package that updates the agreed to business
logic, all organizations that are part of the smart contract endorsement policy should install that
package, or their own version of it, on their peers. Otherwise, after it is committed, the peers that are
running the previous version are no longer able to endorse transactions. This could cause transactions
not being committed to the ledger because there are not enough endorsements to satisfy the
endorsement criteria.
Because this is an update to an existing smart contract definition, you need to use the same smart
contract definition name but it is recommended to increment the version by a second digit. For
example, change the version from 1.1 to 1.2. This second digit version update is a best practice,
which signals channel members that this proposal is an update to an existing smart contract definition
and requires approval.
Update a smart Assuming there are no changes to the agreed to business logic, a smart contract package can be
contract updated without approval from channel members. If there is a change to the logic, see the previous
package after task Update a smart contract definition that has been committed to the channel for the process.
the definition is
committed to the From the Channels tab, open the smart contract tile and click Update package details next to your
channel organization. If you want to install a package that exists on another peer in your organization, select it
from the Existing package tab. Or, click Add file to upload your own version of the smart contract
package. Then select the peers to install it on. Since the smart contract definition is committed, the
peer can immediately begin to process requests for the updated smart contract.
Install the smart It's possible that you approved a smart contract for the channel, but elected to not install it on any of
contract on your peers. Later, you decide you do want to run the package on your peers. From the Channels tab,
peers in my open the smart contract tile and click Update package details next to your organization. If you want to
organization install the existing package, select it from the Existing package tab. Or, upload your own version of
after it has been the smart contract package. Then select the peers to install it on. Since the smart contract definition
committed is committed, the peer can immediately begin to process requests for the smart contract.
Install the smart After the smart contract definition is committed, maybe you need to install the smart contract
contract on package on additional peers or newly created peers. From the Channels tab, open the smart contract
additional or tile and click Update package details next to your organization. If you want to install the existing
new peers after package, select it from the Existing package tab. Or, upload your own version of the smart contract
it is committed package. Then select the peers to install it on. Since the smart contract definition is committed, the
to the channel peer can immediately begin to process requests for the smart contract.
Change the Because the smart contract endorsement policy of a smart contract is agreed to by members of the
smart contract channel before the smart contract can be committed to the channel, the endorsement policy cannot
endorsement be updated without approval of other channel members, as defined in the channel lifecycle
policy of a smart endorsement policy. Therefore, if you need to update the endorsement policy of a smart contract
contract proposal or a committed smart contract, then you need to submit a new proposal with the updated
definition endorsement policy. You do not have to update the smart contract package in this case,but it is
required to increment the smart contract version.
Change the From the Channels tab, click Channel details and click the Settings icon and then click through to the
lifecycle Lifecycle endorsement policy step.
endorsement
policy for the
channel

A new From the Channels tab, click the tile of the proposed smart contract and clickBegin approval
organization process. After providing the identity from your wallet, click Add file to upload the package or Existing
joins the package to select a package already installed on another peer in your organization, and optionally
channel and choose which peers to install it on.
wants to approve
a smart contract
proposal.
A new From the Channels tab, click the tile of the committed smart contract and clickBegin approval
organization process. After providing the identity from your wallet, click Add file to upload the package or Existing
joins the package to select a package that is already installed on another peer in your organization, and
channel and optionally choose which peers to install it on.
wants their peers
to be able to
endorse
transactions for a
committed smart
contract.
Table 2. Frequent smart contract tasks
More details on the lifecycle deployment scenarios are available in the Fabric documentation
Specifying a smart contract endorsement policy

Every smart contract must have a smart contract endorsement policy, that is specified during the smart contract definition. The
endorsement policy specifies the set of organizations, the peers, on a channel that can execute the smart contract and
independently validate the transaction output. For example, an endorsement policy can specify that a transaction is added to
the ledger only if a majority of the members on the channel endorse the transaction. The organization that proposes the
definition can select from among the members who have installed the smart contract to become validators, and sets the
endorsement policy for all channel members. You can update your endorsement policy by following the steps for updating your
smart contract.
When you follow the steps to propose a smart contract definition, you can use the side panel to specify a contract's
endorsement policy after selecting the smart contract package. You have the option to select the default endorsement policy
inherited from the channel configuration or to select specific organizations that have to endorse the transactions as well as how
many endorsements are required. For information about setting a default endorsement policy for a channel, check out the
Advanced options section of our topic on channels.
Click the Advanced tab if you want to specify a custom policy in JSON format. Use this method when you need to specify more
complicated endorsement policies, such as requiring that a certain member of the channel must validate a transaction, along
with a majority of other members. You can more information about the required format in the endorsement policy syntax.
Endorsement policies are not updated automatically when new organizations join the channel and install a smart contract. For
example, if the endorsement policy requires two of five organizations to endorse a transaction, the policy will not be updated to
require two out of six organizations when a new organization joins the channel. Instead, the new organization will not be listed on
the policy, and they will not be able to endorse transactions. You can add another organization to an endorsement policy by
submitting a new proposal to update the smart contract endorsement policy that can be approved by the organizations that are
listed in the channel lifecycle endorsement policy.
What does the user type have to do with the smart contract endorsement policy?
It's worth clicking the Advanced button to review the endorsement policy that will be used for the smart contract. Every
organization that you select from the Members drop-down list on this panel will be included in the endorsement policy
(represented by the role mspId parameter in the policy). The value of the role name parameter indicates the type of identity
that is required to endorse transactions and can be any of client , peer , orderer , admin , or member . If it is set to member ,
then any of the other four roles will satisfy the criteria.

When a peer role is specified, you should ensure that any peers that will be submitting endorsement transactions were
registered with the correct type. In the following endorsement policy example, peers who are members of org1msp can endorse
transactions if their enroll id was registered with the type of client , peer , orderer , or admin . However, for peers who are
members of org2msp , their enroll id must have been registered with a type of peer to be able to endorse transactions. The
OutOf expression indicates that 1 out of the 2 organizations must endorse the transaction.
OutOf(1, 'org1msp.member', 'org2msp.peer')
Unsure which type was selected when a peer identity was registered? From the console, you can open the CA where the peer
identity was registered and view the list of registered users and their associated type.
Versioning a smart contract

It is likely that you will need to modify the smart contract over time as channel members agree to changes in the business logic.
Or, your organization may prefer to implement certain aspects of the logic according to your business needs. Regardless, the
platform recommends using the following convention:
In order to facilitate the smart contract versioning process, package naming should be of the format:
[SMART_CONTRACT_NAME]_[VERSION]
where [VERSION] contains:
n.n when the version requires approval across organizations in the channel. For example,mysmartcontract_1.0.
n.n.n when the version does not require approval from other organizations on a channel. For example,
mysmartcontract_1.0.1. Note that this updated version of the smart contract package cannot introduce any
modifications the to read/write set that could cause transaction endorsement to fail. Use this option to incrementally
patch your smart contract as needed. This means organizations can roll out minor fixes, for example slight variations such
as error checking, to the smart contract independent of other organizations. The important thing is that always, the smart
contract must implement the same reads and the same writes to the ledger across all organizations.
Important: Although this recommended convention is not enforced by Fabric, it provides a standard nomenclature for
you to update the smart contract on your organization's peers without requiring approval from other channel members.
Organizations on the channel can share their smart contract packages with other channel members, out of band, or each
organization can package their own version of the smart contract. But every organization needs to install a package with the
same business logic, to allow transaction endorsement to succeed across all peers on the channel. Each organization needs to
ensure that the smart contract transactions are deterministic. That is, each transaction must always generate the same
transaction response for a given set of transaction inputs. That's because the smart contract is run by multiple organizations,
each of whom must generate the same transaction response. If not, the resulting generated transaction will be captured in the
ledger as invalid, the world state is not updated, and the transaction has no effect on the ledger.
Finally, it is important to recognize that in addition to a smart contract package version, each smart contract definition on the
channel has its own version as well. The following example demonstrates their relationship.
Example versioning scenario
Each row in the table represents a successive step in the smart contract lifecycle when the default channel lifecycle
endorsement policy is used (a majority of organizations must approve the smart contract definition).
Organization Action Smart contract Smart contract

definition version package version
Org1 Propose definition to channel v1.0.0 smartcontract_1.0.0

Org2 Approve definition and install smart contract package v1.0.0 smartcontract_1.0.0
Org3 Approve definition and install own smart contract package v1.0.0 smartcontract_1.0.1
version with additional logging for example
Org3 Commit definition to channel v1.0.0 Org1:

smartcontract_1.0.0
Org2:
smartcontract_1.0.0
Org3:
smartcontract_1.0.1
Org2 Propose update to smart contract definition with new v1.1.0 smartcontract_1.1.0
package
Org1 Approve definition and install own smart contract package v1.1.0 smartcontract_1.1.1
version with enhanced error checking for example
Org3 Abstains because he is on vacation
Org2 Commit definition to channel v1.1.0 Org1:

smartcontract_1.1.1
Org2:
smartcontract_1.1.0
Org3: none
Org3 Update package details and uses own version of smart v1.1.0 smartcontract_1.1.1
contract package
Table 1. Smart contract versioning example
Important: Whenever channel members agree to an update in the business logic, and channel members are running
different custom versions of the smart contract, each member needs to implement the updated business logic in their
own version of the smart contract and repackage it. Blindly installing a smart contract package from another organization
risks overwriting any customizations that you might have added to your version of the smart contract.
Important considerations when you update smart contracts

1. What happens to my peers if I forget to upgrade them to the latest version before committing the smart contract definition
on the channel?
After updating a smart contract definition to use a use smart contract package and committing it to the channel, if there are
still peers on the channel running the previous version, those peers are no longer able to endorse transactions for the
smart contract. Also, you risk not having enough endorsements for transactions to be committed to the ledger, depending
on how the smart contract endorsement policy is defined. However, it is possible to install the new version of the smart
contract package on these peers after the smart contract definition is committed to the channel and the peers will again
be able to endorse transactions, effectively catching up.
2. What happens when I remove an organization from my private data collection?
The peers in that organization continue to store data in the private data collection until its ledger reaches the block that
removes its membership from the collection. After that occurs, the peers will not receive private data in any future

transactions, and clients of that organization will no longer be able to query the private data via a smart contract from any
peer.
3. What happens to the existing chaincode-execution pod after I update my smart contract?
Whenever a transaction is submitted to a smart contract installed on peer, a chaincode-execution pod is launched if one
does not already exist. When you deploy a new version of your smart contract, the chaincode-execution pod for the
previous version of the smart contract continues to run but is no longer required. To save cluster resources, you can
manually delete the chaincode-execution pods for the prior smart contract versions. From your cluster namespace, run
the following command to see the list of chaincode-execution pods that are currently running:
kubectl get pod -n <NAMESPACE> | grep chaincode-execution | cut -d" " -f1 | xargs -I {} kubectl
get po {} -n <NAMESPACE> --show-labels
Replace <NAMESPACE> with the name of your cluster namespace. Your smart contract name and version is visible in the
output under the LABELS column next to chaincode-id . To delete the pod, run the following command:
kubectl delete pod <CHAINCODE-EXECUTION-POD> -n <NAMESPACE>
Replace <CHAINCODE-EXECUTION-POD> with the name of the chaincode-execution pod for the prior version of the smart
contract that is visible in the output of the previous command.
Private data
Private data is a feature of Hyperledger Fabric networks at version 1.2 or higher and is used to keep sensitive information private
from other organization members on a channel. Data privacy is achieved by using private data collections. For example, several
wholesalers and a set of farmers might be joined to a single channel. If a farmer and a wholesaler want to transact privately,
they can create a channel for this purpose. But they can also decide to create a private data collection on the smart contract that
governs their business interactions to maintain privacy over sensitive aspects of the sale, such as the price, without having to
create a secondary channel. To learn more about when to use private data within a blockchain, visit the Private Data concept
article in the Fabric documentation.
In order to use private data with IBM Blockchain Platform, the following three conditions must be satisfied:
1. Define the private data collection. A private data collection file can be added to your smart contract. Then, at run time,
your client application can use private data-specific chaincode APIs to input and retrieve data from the collection. For
more information about how to use private data collections with your smart contract, see the Fabric Secured asset
transfer in Fabric.
2. Install, propose, approve and commit. After you define the smart contract private data collection, you need to use the
smart contract lifecycle process to install the smart contract package along with its private data collection on your
organization peers.
3. Configure anchor peers. Because cross-organizational gossip must be enabled for private data to work, an anchor peer
must exist for each organization in the collection definition. Refer to this information for how to configure anchor peers on
your network.
Your channel is now configured to use private data.
Implicit data collections

Along with the new chaincode lifecycle, Fabric v2.0 introduced the support for "implicit data collections". Whereas private data
collections keep ledger data private among selected organization members, implicit data collections eliminate the need to
define a collection when only a per-organization collection is required. Each organization on the channel has a private data
collection that their own organization peers can use. This collection is implicit, because unlike private data collections, it does
not need to be explicitly defined when a smart contract is deployed. To take advantage of this capability, the channel must be
configured with application capability v2.x and the peers on the channel must be deployed with a Fabric v2.x image. To learn

more about the capability, see Referencing implicit collections from chaincode. To learn how to implement this capability in a
smart contract, see the Secured asset transfer sample.
Deploy a smart contract using Fabric v1.4 (Deprecated)

(Deprecated) Learn how to create and package a smart contract, how to install the smart contract on a peer running a Fabric
1.4 image, and how to instantiate the smart contract on a channel using application capability 1.x.
smart contract.
Important: While the terms "smart contract" and "chaincode" are often used interchangeably, "smart contracts" refers to
the business logic that governs transactions and access to its data, while "chaincode" refers to the larger infrastructure of
packages and other code that encompasses a smart contract.
Smart contracts are installed on peers and then instantiated on channels. All members that want to submit transactions or
read data by using a smart contract need to install the contract on their peer. A smart contract is defined by its name and
version. Therefore, both the name and version of the installed contract need to be consistent across all peers on the channel
that plan to run the smart contract.
After a smart contract is installed on the peers, a single network member instantiates the contract on the channel. The network
member needs to have joined the channel in order to perform this action. Instantiation updates the ledger with the initial data
that is used by the smart contract, and then starts smart contract pods. The peers can then use the smart contract.
Only one network member needs to instantiate a smart contract.

If a peer with a smart contract installed joins a channel where the same smart contract version has already been
instantiated, the smart contract container starts automatically.
In this tutorial, we go through the steps to use the IBM Blockchain Platform console to manage the deployment of smart
contracts on your network:
Write and package your smart contract.

Install smart contracts on your peers.
Instantiate them on channels.
Specify endorsement policies.
Upgrade the smart contract policies and code.
Before you begin

Before you can install a smart contract, ensure that you have the following things ready.
You must either build a network or join a network by using your IBM Blockchain Platform console.
Because smart contracts are installed onto peers, ensure that you add peers to your console.
Smart contracts are instantiated on a channel. Therefore, you must create a channel or join a channel by using your
console.
The IBM Blockchain Platform supports smart contracts written in JavaScript, TypeScript, Java, and Go. When you are
allocating resources to your peer node, it is important to note that JavaScript and TypeScript smart contracts require more
resources than contracts written in Go.

The IBM Blockchain console manages the deployment of smart contracts rather than development. If you are interested in
developing smart contracts, you can get started using tutorials provided by the Hyperledger Fabric community and tooling

provided by IBM.
To learn how smart contracts can be used to conduct transactions among multiple parties, see the Developing
applications topic in the Hyperledger Fabric documentation.
When you are ready to start building smart contracts, you can use the IBM Blockchain Visual Studio code extension to
start building your own smart contract project. You can also use that extension to connect directly to your network from
Visual Studio Code and explore the inline tutorials.
For a quick tutorial on developing smart contracts, see Develop a smart contract with the IBM Blockchain Platform VS
Code extension.
For a more in-depth end-to-end tutorial about using an application to interact with smart contracts, see Hyperledger
Fabric Commercial Paper tutorial.
To learn about how to incorporate access control mechanisms into your smart contract, see Chaincode for Developers.
Important: Because Fabric v2.x peers do not have a "shim" (the external dependencies that allowed smart contracts to
run on earlier versions of Fabric), you will have to vendor the shim and then repackage any smart contracts written in
Golang (Go) that you installed on peers deployed using the 1.4.x Fabric image. Without this vendoring and repackaging,
the smart contract will not run on a peer using a Fabric 2.x image. You will not need to do this on smart contracts that are
written in Java or Node.js, nor for smart contracts written and packaged using the 2.0 package. See Vendoring smart
contracts for details.
When you are ready to install and instantiate your smart contract to the IBM Blockchain platform, the smart contract must be
packaged into .cds format. For more information, see Packaging smart contracts. Alternatively, you can use peer CLI
commands to build the package. For v1.4.x commands, see 1.4.x peer CLI commands.

If your smart contract uses the fabric-chaincode-go shim or the Go contract-api you need to repackage the smart contract
before it can be installed on a peer that is running a Fabric v2.x image.
Why is vendoring the shim required?
In Fabric v1.4.x, the Go chaincode shim and protocol buffers (protos) were included with the Fabric distribution and were
included in the Go chaincode runtime in the IBM Blockchain Platform. Starting with v2.0, Fabric now provides the chaincode
shim and protos as separate repositories that need to be imported or "vendored" in Go smart contracts before they can be
installed on a peer that runs a Fabric v2.x image. To vendor the shim for your Go smart contract, navigate to your smart contract
source folder and initialize the Go module by issuing the following command which creates a go.mod file:
go mod init
Add the required imports to go.mod by running the following command:
go test
The go.mod file will resemble:
$ module mysmartcontract
go 1.14
require (
github.com/hyperledger/fabric-chaincode-go v0.0.0-20200511190512-bcfeb58dd83a
github.com/hyperledger/fabric-protos-go v0.0.0-20200506201313-25f6564b9ac4
)
or if you are using the Go contract-api , it will resemble:

$ module github.com/hyperledger/fabric-samples/chaincode/fabcar/go
go 1.13
require github.com/hyperledger/fabric-contract-api-go v1.1.0
You can then get the necessary dependencies to install the Go smart contract on a 2.x peer by issuing the following command
that completes the vendoring of the smart contract:
go mod tidy
go mod vendor
See the Go documentation to learn more about what these commands do.
Package Construction
The following example shows the folder structure of a "marbles" smart contract that uses the fabric-chaincode-go shim before
the vendoring process:
$ ├── META-INF
└── util
└── util.go
And after the vendoring process, the structure is as follows:
$
├── META-INF
├── go.mod
├── go.sum
├── util
│ └── util.go
└── vendor
├── github.com
│ ├── golang
│ │ └── protobuf
│ └── hyperledger
│ ├── fabric-chaincode-go
│ └── fabric-protos-go
├── golang.org
├── google.golang.org
└── modules.txt
Note: The source directory must be the smart contract name which is "marbles" in this case. Therefore, the import for the
util package in the smart contract would be:
import "marbles/util"
After you have completed these steps, you need to repackage your smart contract using the process that is described in
Packaging smart contracts.
Tip: Fabric-contract-api and fabric-shim node modules must be at v1.4.5 or greater to work with Node version 12. If you

are using a smart contract that was originally written to work with Fabric 1.4, check the node modules before deploying
your smart contract on a peer that runs a Fabric v2.x image.
Step two: Install a smart contract

Use your console to perform these steps:
1. Click the Smart contracts tab to install one or more smart contracts.
2. Click Install smart contract to upload the smart contract package file in .cds format. The smart contract package file must
be less than 25 MB in size. You can use the IBM Blockchain Visual Studio Code extension to create a smart contract
package. When you install the package from the Smart contracts tab, you can select one or more peer nodes to install the
smart contracts on.
If only one peer exists in the console, the smart contract will be installed on it. You are not prompted to select a peer to install
the smart contract on. You can navigate to the nodes tab and click a peer that is managed by your console to view the list of
smart contracts installed on an individual peer.
Tip: You can return to the Smart contracts tab later to install the smart contract on additional peers, even after the smart
contract was instantiated on the channel. If the version of the smart contract that you install is the same as the
instantiated version, these additional peers can process transactions just like the existing peers.
This console cannot be used to install Hyperledger Composer.bna files.
Step three: Instantiate a smart contract

Smart contracts are instantiated on a channel. Any console member with peers joined to a channel can instantiate a smart
contract and specify the associated endorsement policy.
Use your console to perform these steps:
1. On the smart contracts tab, find the smart contract from the list of smart contracts that are installed on your peers and
click Instantiate from the overflow menu on the right side of the row.
2. On the side panel that opens, select a channel to instantiate the smart contract on. You can select the channel, named
channel1, which you created. Then, click Next.
3. Specify the endorsement policy for the smart contract, described in the following section. When multiple organizations
are members of the channel, you have the opportunity choose how many organizations are required to endorse the smart
contract transactions.
4. You also need to select the organization members to be included in the endorsement policy. If you are following along in
the tutorial, that would be org1msp and possibly org2msp if you completed both the Build a network and Join a network
tutorials.
5. On the Select peer panel, select a peer from the drop-down list that is from an organization that is a member of the
channel.
6. If your smart contract includes Fabric private data collections, you need to upload the associated collection configuration
JSON file, otherwise you can skip this step. For more information, see private data.
7. On the last panel, you are prompted to specify the name of the smart contract initialization function, along with the
associated arguments to pass to that function.
You can view all of the smart contracts that are instantiated on a channel by clicking the channel icon in the left navigation,
selecting a channel from the table, and then clicking the Channel details tab.
Tip: Be aware that if you use a free Kubernetes cluster on IBM Cloud, instantiation can take significantly longer than in a
paid cluster.Depending on the number of peers you have deployed in your cluster, the type of smart contract you are
instantiating, and the platform you are running on, instantiation can take several minutes. If the instantiation fails with a
timeout error, wait 5 minutes and then retry it again.

The combination of installation and instantiation is a powerful feature because it allows for a peer to use a single smart
contract across many channels. Peers may want to join multiple channels that use the same smart contract, but with different
sets of network members able to access the data. A peer can install the smart contract once and use it on any channel where it
has been instantiated. This lightweight approach saves compute and storage space, and helps you scale your network.
Step four: Send transactions by using your client applications

After a smart contract has been instantiated on a channel, you can use a client application to transact with other members of
your network. Applications can invoke the business logic that is contained in smart contracts to create, transfer, or update assets
on the blockchain ledger.
Connect with SDK

After you create an organization MSP definition, you can download a connection profile that can be used by a client application to
connect to your network via one or more gateway peers. The gateway peers are the peers that are specified in the connection
profile, and they are used to perform service discovery to find all of the endorsing peers in the network that will endorse
transactions.
Click the Organization MSP tile for the organization that your client application interacts with. ClickCreate connection profile to
open a side panel where you can build and download your connection profile.
If you plan to use the client application to register and enroll users with the organization CA, you need to include the Certificate
Authority in the connection profile definition.
Select the peers to include in the connection profile definition. When a peer is not available to process requests from a client
application, service discovery ensures that the request is automatically sent to a different peer. Therefore, to accommodate for
peer downtime during a maintenance cycle for example, it is recommended that you select more than one peer for redundancy.
In addition to peers created by using the console or APIs, imported peers that have been imported into the console are eligible
to be selected as well.
The list of channels that the selected peers have joined is also provided for your information. If a channel is missing from the list,
it is likely because the peer joined to it is currently unavailable.
You can then download the connection profile to your local file system and use it with your client application to generate
certificates and invoke smart contracts.
Note: The connection profile that is downloaded from the IBM Blockchain Platform console can only be used to connect
to your network by using the Node.js (JavaScript and TypeScript) and Java Fabric SDKs.
The generated connection profile only supports Fabric CAs. If you manually built your organization MSP with certificates from an

external CA, the connection profile will not include any information in the "certificateAuthorities": section.
Specifying an endorsement policy

Every smart contract must have an endorsement policy, that is specified during instantiation. The endorsement policy specifies
the set of organizations, the peers, on a channel that can execute the smart contract and independently validate the transaction
output. For example, an endorsement policy can specify that a transaction is added to the ledger only if a majority of the
members on the channel endorse the transaction. The organization that instantiates the smart contract can select from among
the members who have installed the smart contract to become validators, and sets the endorsement policy for all channel
members. You can update your endorsement policy by following the steps for updating your smart contract.
When you follow the steps to instantiate a smart contract, you can use the side panel to set a contract's endorsement policy
after selecting the channel. Use this panel to specify a simple policy by selecting the peers that need to endorse the transaction
from the list of peers that have installed the smart contract on the channel. You can use this method to specify an endorsement
policy of all channel members, a majority of them, a single member, or a simple +1 preventing members from self-signing. The
default endorsement policy is set to 1 of x , meaning that only a single member of the channel is required to endorse a smart
contract transaction.
Click the Advanced button if you want to specify a policy in JSON format. You can use this method to specify more complicated
endorsement policies, such as requiring that a certain member of the channel must validate a transaction, along with a majority
of other members. You can find additional examples of advanced endorsement policies in the Hyperledger Fabric
documentation. For more information about writing endorsement policies in JSON, see Hyperledger Fabric Node SDK
documentation.
Endorsement policies are not updated automatically when new organizations join the channel and install a smart contract. For
example, if the endorsement policy requires two of five organizations to endorse a transaction, the policy will not be updated to
require two out of six organizations when a new organization joins the channel. Instead, the new organization will not be listed on
the policy, and they will not be able to endorse transactions. You can add another organization to an endorsement policy by
upgrading the relevant smart contract and updating the policy.
It's worth clicking the Advanced button to review the endorsement policy that will be used for the smart contract. Every
organization that you select from the Members drop-down list on this panel will be included in the endorsement policy
(represented by the role mspId parameter in the policy). The value of the role name parameter indicates the type of identity
that is required to endorse transactions and can be any of client , peer , orderer , admin , or member . If it is set to member ,
then any of the other four roles will satisfy the criteria.
When a peer role is specified, you should ensure that any peers that will be submitting endorsement transactions were
registered with the correct type. In the following endorsement policy example, peers who are members of org1msp can endorse
transactions if their enroll id was registered with the type of client , peer , orderer , or admin . However, for peers who are
members of org2msp , their enroll id must have been registered with a type of peer to be able to endorse transactions.
{
"identities": [
{
"role": {
"name": "member",
"mspId": "org1msp"
}
},
{
"role": {
"name": "peer",
"mspId": "org2msp"

}
}
],
"policy": {
"1-of-2": [
{
"signed-by": 0
}
]
}
}
Unsure which type was selected when a peer identity was registered? From the console, you can open the CA where the peer
identity was registered and view the list of registered users and their associated type.
Upgrading a smart contract

You can upgrade a smart contract to change its code, endorsement policy, or private data collection while maintaining its
relationship to the assets on the ledger. There are a variety of reasons why you may want to upgrade an instantiated smart
contract.
1. You can upgrade the smart contract to add or remove functionality from its code and iterate on the logic of your business
network.
2. Whenever a new member is added to a channel, the endorsement policy of the instantiated smart contractsmust be
updated to include the new channel member. In order to work with the new channel member, the smart contract must be
repackaged with a new version number and instantiated on the channel, even if the smart contract itself is unchanged.
Otherwise, transaction endorsement cannot succeed.
3. When a private data collection has changed, for example an organization is added or removed you need to upgrade your
smart contract. Or, use this action whenever a new private data collection is added to the collection configuration JSON
file.
4. The smart contract initialization arguments have changed.
Note: Before you upgrade an instantiated smart contract, the new version of the smart contract must be installed on all
peers in the channel that are running the previous level of the smart contract.
Important: Be aware that after you have upgraded your peers to the v2.x image and switched your application channel
capability to 2.0, you can no longer upgrade your smart contract using the instructions in this topic. Instead, you need to
repackage your smart contract and deploy the smart contract on the network using Fabric v2.x.
How to upgrade a smart contract

To upgrade a smart contract, install the updated code by specifying the same smart contract name but by using and a new
version number. If you have installed a newer version of a smart contract on any peer in the channel, notice that the original
version now has the Upgrade Available button next to it in the Instantiated smart contracts table.
When a new member that will run the smart contract joins the channel, it is mandatory to update the smart contract by installing
a new version on all the peers and instantiating it on the channel with a modified endorsement policy that includes the new
member.
Navigate to the Smart contracts tab on the left.

Scroll down to the Instantiated smart contracts table.
In the Instantiated smart contracts table, locate the smart contract version and channel that you want to upgrade. It
must have the Upgrade Available label next to it.
Click the overflow menu on the right side of the smart contract row and clickUpgrade to perform the following steps:

1. Select the smart contract version that you want to upgrade on the channel from the drop-down list.
2. Update the endorsement policy by adding or removing channel members. You can also clickAdvanced to paste in a
new JSON formatted string, which modifies the existing policy.
3. On the Select peer panel you need to select a peer that can approve the proposal to upgrade the smart contract.
Therefore, you need to select a peer from the drop-down list that is from an organization that was a member of the
channel before the smart contract was last instantiated on the channel.
4. If you want to associate a private data collection configuration file with the smart contract you can upload the JSON
file. Or if you want to update an existing collection configuration, you can upload the JSON file. If the smart contract
was previously instantiated with a collection configuration file, you must again upload the previous version or a new
version of the collection configuration file during this step.
5. (Optional) Modify the smart contract initialization argument values if the parameters have changed. If you are
unsure about it, check with your smart contract developer. If they have not changed, you can leave this field blank.
After you upgrade the smart contract, you will change the version of the contract that is instantiated on the channel. If you are
using private data collections, be sure you have configured anchor peers on the channel.
Considerations when you upgrade smart contracts

1. Do I need to install the new version of the smart contract on all my peers?
When a smart contract is invoked on a peer, it attempts to run the version that is instantiated on the channel. If a previous
version is running on the peer, it results in an error. Therefore, before you upgrade a smart contract on a channel, it is a
best practice to install the latest version of the smart contract on all peers that are running the previous version.
2. Can a subsequent smart contract version still process data on the ledger from a prior version of the smart contract?
Yes. As long as the new smart contract code addresses the data in a compatible way (by adding new JSON fields and not
changing the semantics or type of the existing fields), any subsequent version of the smart contract can run against the
data from a prior version.
3. What happens to my peers if I forget to upgrade them to the latest version before updating the smart contract on the
channel?
After updating the channel to use the new version of the smart contract, if there are still peers on the channel running the
previous version, those peers are no longer able to endorse transactions for the smart contract. Also, you risk not having
enough endorsements for transactions to be committed to the ledger, depending on how the smart contract endorsement
policy is defined. However, it is possible to install the new version of the smart contract on these peers later and they will
again be able to endorse transactions, effectively catching up.
4. What happens when I remove an organization from my private data collection?
The peers in that organization continue to store data in the private data collection until its ledger reaches the block that
removes its membership from the collection. After that occurs, the peers will not receive private data in any future
transactions, and clients of that organization will no longer be able to query the private data using a smart contract from
any peer.
Private data
Private data is a feature of Hyperledger Fabric networks at version 1.2 or higher and is used to keep sensitive information private
from other organization members on a channel. Data privacy is achieved by using private data collections. For example, several
wholesalers and a set of farmers might be joined to a single channel. If a farmer and a wholesaler want to transact privately,
they can create a channel for this purpose. But they can also decide to create a private data collection on the smart contract that
governs their business interactions to maintain privacy over sensitive aspects of the sale, such as the price, without having to
create a secondary channel. To learn more about when to use private data within a blockchain, visit the Private Data concept
article in the Fabric documentation.

In order to use private data with IBM Blockchain Platform, the following three conditions must be satisfied:
1. Define the private data collection. A private data collection file can be added to your smart contract. Then, at run time,
your client application can use private data-specific chaincode APIs to input and retrieve data from the collection. For
more information about how to use private data collections with your smart contract, see the Fabric SDK tutorial on Using
private data in the Fabric SDK documentation.
2. Deploy the smart contract. After you define the smart contract private data collection, you need to install the smart
contract on the peers that are members of the channel. When you instantiate the smart contract on the channel by using
the console, you need to upload the collection configuration JSON file. For more information on how to create a collection
definition JSON file see the Fabric SDK documentation topic.
Instead of using the console to install and instantiate your smart contract with a collection config file, you can also use the
Fabric SDK. Those instructions are also available under How to use private data in the Node SDK documentation.
Note: A client needs to be an admin of your peer in order to install or instantiate a smart contract by using the SDK.
Therefore, you need to download the certificates of the peer admin identity from your console wallet and pass the peer
admin's signing certificate and private key to directly to the SDK instead of creating an application identity. For an example
of how to pass a key pair to the SDK, see Connecting to your network by using low-level Fabric SDK APIs.
3. Configure anchor peers. Because cross organizational gossip must be enabled for private data to work, an anchor peer
must exist for each organization in the collection definition. Refer to this information for how to configure anchor peers on
your network.
Your channel is now configured to use private data.

Developing applications
After you install smart contracts (chaincode) and deploy your peer and ordering nodes, you are ready to develop client
applications to transact with other members of your IBM Blockchain Platform network. Applications invoke the business logic
contained in smart contracts to create, transfer, and update assets on the blockchain ledger. Use this page to learn how to use
client applications to interact with networks from the IBM® Blockchain Platform console.
Target audience: This topic is designed for application developers who are interested in developing client apps for an IBM
Blockchain Platform network, in Node.js, Go, or Java.
Using the v2.4 Fabric Gateway peer service

IBM Blockchain Platform v2.5.3 adds support for the v2.4 Hyperledger Fabric Gateway peer service, which introduces an
updated model for developing applications. The v2.4 gateway peer model relocates node connection and transaction processing
requirements from the client application to the v2.4 peer nodes. The v2.4 Fabric Gateway method therefore enables developers
to focus on business solutions, without having to code gateway connection or transaction processing logic in client applications,
as is required for earlier releases.
Supported app development methods in Fabric v2.4

To develop new applications for IBM Blockchain Platform v2.5.3, using the latest v2.4 Hyperledger Fabric Gateway peer service
and API are recommended, as documented in Running a Fabric Application. However, for existing applications developed for
IBM Blockchain Platform v2.5.2 and earlier, no migration is required— your existing applications will continue to run on v2.5.3.
In addition, the prior Hyperledger Fabric v2.2 (and earlier) development methods, using the legacy SDKs (both high-level and
low-level programming models), remain supported for new applications in IBM Blockchain Platform v2.5.3 and Fabric v2.4.
Important: Although legacy applications will continue to run on v2.5.3, upgrading development methods to use the v2.4
Fabric Gateway API as soon as possible is recommended.
Fabric Peer Gateway documentation

For details on developing new applications for Hyperledger Fabric v2.4 networks, refer to the v2.4 Fabric Gateway
documentation. The documentation includes v2.4 Fabric Gateway samples, connection details, and related client application
development topics.
Connecting to the Fabric Gateway peer service

A client application that uses the v2.4 Fabric Gateway peer service needs to specify the connection details for the target peer.
The recommended method for retrieving peer connection information is to download the connection profile for your
organization, which contains the peer endpoint URL, and the TLS Root CA certificate in pem format, required for the client
application to connect.
Attention: The peer endpoint URL in the downloaded connection profile starts with grpcs:// , which is not recognized as part
of the endpoint URL. The endpoint URL is therefore the url field in the peer connection profile, with the grpcs:// prefix
removed. Peer node details in the organization connection profile will look similar to the following example:
$ "url": "grpcs://n257768-org1peer1.us-east.containers.appdomain.cloud:7051",
"tlsCACerts": {
"pem": "-----BEGIN CERTIFICATE-----
\nMIICCzCCAbKgAwIBAgIUYH1G2I60YOEZuiAQPsvSmWXABxUwCgYIKoZIzj0EAwIw\nZDELMAkGA1UEBhMCVVMxFzAVBgNVBAg
< MATERIAL REMOVED FOR BREVITY AND SECURITY>
DAQH/MB0GA1UdDgQWBBRDV6AdNnpIEGO9\n7mbUM5bk4U0/yTAKBggqhkjOPQQDAgNHADBEAiAxjAM3zkf4v0TXUlJZZgS4TFE5\nY7eO7e16X1rETFr

-----END CERTIFICATE-----\n"
},
"grpcOptions": {
"ssl-target-name-override": "n257768-org1peer1.us-east.containers.appdomain.cloud"
}
Click the Organization MSP tile for the organization that your client application interacts with. Click Create connection profile to
Attention: The remainder of this page describes the Fabric v2.2 and earlier methods for developing applications, which remain
supported in IBM Blockchain Platform v2.5.3 and Fabric v2.4. (IBM Blockchain Platform does not support Hyperledger Fabric
v2.3). The Fabric v2.2 and earlier development methods are described as the high-level programming model and SDKs and its
predecessor, the low-level programming model.
Legacy model of developing applications
Important: This section describes the legacy model of developing applications, which was designed for Hyperledger
Fabric v2.2 and earlier. Refer to the previous section on using the v2.4 Fabric Gateway peer service for details on
developing new applications for Fabric v2.4.
Developing an application might require coordination between two distinct users of your network, the network operator and the
application developer:
The network operator is the administrator who uses the IBM Blockchain Platform console to deploy the nodes of your
organization and installs the smart contracts on your network.
The application developer builds the client application that is consumed by users. The developer uses the Hyperledger
Fabric SDKs to invoke transactions written in the smart contracts.
If you are the network operator, you will need to complete the following steps before the application developer can interact
with your network:
1. Use your organization CA to register an application identity.

2. Download the connection profile from the organizations panel.
3. Send the application developer the following objects and information:
The enroll ID and secret of the application identity.
The connection profile.
The smart contract name.
The name of the channel the smart contract was deployed on.
If you are the application developer, use the information that is provided by the network operator to complete following steps:
1. Generate a certificate and private key by using the enroll ID and secret of the application identity, along with CA endpoint
information inside your connection profile.
2. Configure a connection by using the Fabric SDK gateway and enable service discovery.
3. Use the connection profile, channel name, smart contract name, and application keys to invoke the smart contract.
Note: The connection profile that you downloaded from the IBM Blockchain Platform console can be used to connect to
your network by using the Node.js (JavaScript and TypeScript), Java, and Go Fabric SDKs.
The application developer can use two programming models to interact with the network, either the High-Level Programming
Model APIs or the Low-Level Fabric SDK APIs.
High-Level Programming Model APIs

Starting with Fabric v1.4, a simplified application and smart contract programming model, known as the fabric-network API,
was introduced, and is now the recommended way to develop applications. The new model reduces the number of steps and
amount of code that is required to submit transactions, which are written in Node.js, Java, or Go. The Fabric High-Level
Programming Model APIs include the High-level Fabric Gateway SDKs for writing client applications and the High-Level Fabric
contract APIs for writing smart contracts. This tutorial focuses on using the High-level Fabric Gateway SDKs.
IBM recommends the High-level Fabric Gateway SDKs which allow client applications to interact with IBM Blockchain Platform
networks. These SDKs, available for Node, Java, and Go, allow a client application to invoke smart contracts for the purpose of
submitting transactions and evaluating queries. It is recommended that administrative tasks, such as creating channels,
deploying smart contracts, are done by using the console, APIs, or Ansible scripts.
Important: The SDKs use the concept of a "Gateway" object to represent the connection of a single identity (user) to a
blockchain network. For performance reasons, applications need to keep a gateway object instance in scope for as long as
it is required, and can use it to submit multiple transactions across different smart contracts and network channels. If an
application needs to handle multiple user identities, then a separate gateway object instance should be maintained for
each identity.
Refer to the SDK documentation for each language for details:
Java
Node
Go
For best practices and examples of how to use the SDKs see the Fabric Asset Transfer Sample
For information about migrating your applications created using the v1.4 SDK to the 2.x SDK, check out Migrating client
applications from v1.4 to v2.0.
Note: Client applications can leverage the capabilities of the Go SDK in the high-level programming model in the gateway
package
If you want to take advantage of the High-Level Fabric contract-APIs, you can also use this tutorial to complete the following
actions on an IBM Blockchain Platform network:
Generate certificates for your application by using the SDK.

Invoke a smart contract from the SDK.
Learn about application development by deploying the commercial paper tutorial to the nodes managed from your
console.
Low-Level Fabric SDK APIs**

If you want to continue to use your existing smart contract and application code, or use the other Fabric SDK languages that are
provided by the Hyperledger community, you can use the low-level Fabric SDK APIs to connect to your network.
Application connectivity and availability

The Hyperledger Fabric Transaction Flow spans multiple components, with the client applications playing a unique role. The
SDK submits transaction proposals to the peers for endorsement. It then collects the endorsed proposals to be sent to the
ordering service, which then sends blocks of transactions to the peers to be added to channel ledgers. Developers of production
applications need to be prepared to manage their interactions between the SDK and their networks for efficiency and availability.
Network considerations

Regardless of whether you choose to use the high-Level Fabric contract APIs, or the low-Level Fabric SDK APIs, both require
network access to the following components:
The CA for your organization. (You should never need to access the CA for another organization).
All organizations peers (where all organizations are the organizations that are required for endorsing transactions).
All ordering service nodes for all channels that you are transacting on.
You must ensure that the hostnames of these components are resolvable by DNS lookup (or /etc/hosts if you cannot correctly
configure DNS). You must also ensure that all of the network ports for these components are accessible to the systems that are
running your applications that are using the Hyperledger Fabric SDKs. The hostname and port for each node are visible in the
console. Open the CA, peer, or ordering node tile and then click the Info and usage tab. The API URL field contains the
hostname and port for the node.
Application compatibility
For your planning purposes, the following SDK and smart contract compatibility matrices have been tested and validated.
SDKs
Click the Java SDK or Node SDK tab for details.
Version Peer Fabric image Java
Java SDK Version 2.2 2.2 Java 8

Java 11
Java SDK Version 1.4 1.4 Java 8

Java 11
Table 1. Java SDK
Version Peer Fabric image Node
Node SDK Version 2.2 2.2 Node 10 LTS

Node 12 LTS
Node SDK Version 1.4 2.2, 1.4 Node 10 LTS

Node 12 LTS
Table 1. Node SDK
Smart contracts
Click the Java Smart contract or Node Smart contract tab for details.
Contract API Peer Fabric image Java runtime
v1.4, v2.2 v2.2 Java 11 runtime
v1.4, v2.2 v1.4 Java 11 runtime
Table 2. Java Smart contract

Contract API Peer Fabric image Node runtime
v1.4, v2.2 v2.2 Node 12 runtime
v1.4 v1.4 Node 8 runtime
Table 2. Node Smart contract
Note: Java and Node runtime versions are determined by IBM Blockchain Platform peer Fabric image and cannot be
changed. These runtimes are different from the default Hyperledger Fabric runtimes.
For more details on smart contract-API compatibility, see:
Java smart contract-API compatibility

Node smart contract-API compatibility
Registering an application identity

Applications need to sign the transactions they submit to IBM Blockchain nodes, and attach a signing certificate that is used by
nodes to verify that the transactions are being sent by the proper party. This ensures that transactions are submitted by the
organizations that have permission to participate.
The network operator needs to use the organization's CA to register an application identity, which can then be used by the
application developer to generate a certificate and private key. The operator can provide the enroll ID and secret of the identity,
along the CA endpoint information, to be used by the SDK to generate certificates. By enrolling on the client side, the application
developer ensures that no other party has access to the private key of the application. During registration, the network operator
can set an enrollment limit of one for additional security. After the application developer enrolls, the enroll ID and secret cannot
be used to generate another private key.
If you are less worried about security, the network operator can enroll an application identity by using the CA tab. The operator
can then download the identity or export it to the console wallet. In order to use the certificates from the SDK, you need to
convert the keys from base64 into PEM format. You can decode the certs by running the following command on your local
system:
export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
echo <base64_string> | base64 --decode $FLAG > <key>.pem
Downloading your connection profile

A client application connects to a network via one or more gateway peers. The gateway peers are the peers that are specified in
the connection profile, and they are used to perform service discovery to find all of the endorsing peers in the network that will
endorse transactions. Service discovery ensures that the request is sent to a peer that is available to process requests.
The Hyperledger Fabric Transaction Flow spans multiple components, with the client applications collecting endorsements
from peers and sending endorsed transactions to the ordering service. The connection profile provides your application with the
endpoints of the peers and ordering nodes that it needs to submit a transaction. It also contains information about your
organization, such as your Certificate Authorities and your MSP ID. The Fabric SDKs can read the connection profile directly,
without you having to write code that manages the transaction and endorsement flow.

Service discovery
Service discovery allows your applications to dynamically find the peer and ordering endpoints of your network. If you do not use
service discovery, you need to manually add the endpoint information of peer and ordering nodes on your channel to your
connection profile or your application. You would need to edit your connection profile or update your application each time a
node is added or removed from your network.
Before you can take advantage of the Service Discovery feature of Hyperledger Fabric, you must configure anchor peers on the
channel. Service discovery allows your application to learn which peers on the channel outside your organization need to
endorse a transaction. Without service discovery, you will need to get the endpoint information of these peers out of band from
other organizations and add them to your connection profile. For more information, see Configuring anchor peers.
Later in this topic, we use the connection profile to build a Fabric gateway that is configured for service discovery.
Enrolling by using the SDK

Once the network operator provides the enroll ID and secret of the application identity and the network connection profile, an
application developer can use the Fabric SDKs or the Fabric CA client to generate client-side certificates. You can use the
following steps to enroll an application identity by using the Fabric SDK for Node.js.

1. Save the connection profile to your local system and rename itconnection.json.
2. Save the following code block as enrollUser.js in the same directory as your connection profile:
'use strict';
const FabricCAServices = require('fabric-ca-client');

const { FileSystemWallet, X509WalletMixin } = require('fabric-network');
const fs = require('fs');
const path = require('path');
const ccpPath = path.resolve(__dirname, 'connection.json');

const ccpJSON = fs.readFileSync(ccpPath, 'utf8');
const ccp = JSON.parse(ccpJSON);
async function main() {

try {
// Create a new CA client for interacting with the CA.

const caURL = ccp.certificateAuthorities['<CA_Name>'].url;
const ca = new FabricCAServices(caURL);
// Create a new file system based wallet for managing identities.

const walletPath = path.join(process.cwd(), 'wallet');
const wallet = new FileSystemWallet(walletPath);
console.log(`Wallet path: ${walletPath}`);
// Check to see if we've already enrolled the admin user.

const userExists = await wallet.exists('user1');
if (userExists) {
console.log('An identity for "user1" already exists in the wallet');
return;
}
// Enroll the admin user, and import the new identity into the wallet.
const enrollment = await ca.enroll({ enrollmentID: '<app_enroll_id>', enrollmentSecret:
'<app_enroll_secret>' });
const identity = X509WalletMixin.createIdentity('<msp_id>', enrollment.certificate,
enrollment.key.toBytes());
await wallet.import('user1', identity);
console.log('Successfully enrolled client "user1" and imported it into the wallet');
} catch (error) {
console.error(`Failed to enroll "user1": ${error}`);
process.exit(1);
}
}
main();
3. Edit enrollUser.js to replace the following values:
Replace <CA_Name> with the name of your organizations CA. You can find your CA name in the "organizations"
section of your connection profile under "Certificate Authorities". Do not use the "caName" in the "Certificate
Authorities" section.
Replace <app_enroll_id> with the application enroll ID provided by your network operator.
Replace <app_enroll_secret> with the application enroll secret provided by your network operator.
Replace <msp_id> with the MSP ID of your organization. You can find your MSP ID under the "organizations" section
of your connection profile.
4. Navigate to enrollUser.js using a terminal and run node enrollUser.js . If the command runs successfully, you
should see the following output:
Successfully enrolled client "user1" and imported it into the wallet

The SDK will create and store your certificates inside the wallet/user1/ directory that is created by the command. This
directory is the file system wallet that is used submit future transactions.
Note: The wallets that are used by the Fabric SDKs are different from the wallet in the IBM Blockchain Platform console.
The identities that are stored in your console wallet cannot be directly used by the SDK.
Invoking a smart contract by using the SDK

After you generate the application signing certificate and private key and store them in a wallet, you are ready to submit a
transaction. You need to know the name of the smart contract and the name of the channel it was deployed on. You can use the
following steps to invoke a smart contract with the Fabric SDK for Node.js.
1. Save the following text on your local machine as invoke.js in the same directory as enrollUser.js .
'use strict';
const { FileSystemWallet, Gateway } = require('fabric-network');


try {
// Parse the connection profile. This would be the path to the file downloaded
// from the IBM Blockchain Platform operational console.
const ccpPath = path.resolve(__dirname, 'connection.json');
const ccp = JSON.parse(fs.readFileSync(ccpPath, 'utf8'));
// Configure a wallet. This wallet must already be primed with an identity that
// the application can use to interact with the peer node.
const walletPath = path.resolve(__dirname, 'wallet');
const wallet = new FileSystemWallet(walletPath);
// Create a new gateway, and connect to the gateway peer node(s). The identity
// specified must already exist in the specified wallet.
const gateway = new Gateway();
await gateway.connect(ccp, { wallet, identity: 'user1' , discovery: {enabled: true,
asLocalhost:false }});
// Get the network channel that the smart contract is deployed to.
const network = await gateway.getNetwork('<channel_name>');
// Get the smart contract from the network channel.

const contract = network.getContract('<smart_contract_name>');
// Submit the 'createCar' transaction to the smart contract, and wait for it
// to be committed to the ledger.
await contract.submitTransaction('createCar', 'CAR12', 'Honda', 'Accord', 'Black', 'Tom');
console.log('Transaction has been submitted');
await gateway.disconnect();
} catch (error) {
console.error(`Failed to submit transaction: ${error}`);
process.exit(1);
}
}
main();
2. Edit invoke.js to replace the following values:
Replace <channel_name> with the name of the channel the smart contract was deployed on. You can find your CA
name under the "Certificate Authorities" section of your connection profile.

Replace <smart_contract_name> with the name of the installed smart contract. You can get this value from your
network operator.
Edit the contents of submitTransaction to invoke a function inside your smart contract. Theinvoke.js file is
written to invoke the FabCar smart contract. If you want to run the following file to submit a transaction, install
FabCar and instantiate the smart contract on one of your channels.
3. Navigate to invoke.js using a terminal and run node invoke.js . If the command runs successfully, you should see
the following output:
Transaction has been submitted
If you navigate to your channel by using the console, you are able to see that another block was added by the transaction.
Note: Your transaction might fail if you did not configure an anchor peer on your channel. Unless you manually updated
your connection profile, your application needs to use the Service Discovery feature to learn about the peers it needs to
submit the transaction to. For more information, see Configuring anchor peers.
Running the Commercial Paper sample

The commercial paper tutorial in the Hyperledger Fabric documentation takes developers through a use case in which multiple
parties buy, sell, and redeem commercial paper. It extends the Developing applications topic by providing sample smart
contract and application code that allows you to create and trade assets on a local instance of Fabric.
You can also deploy the commercial paper tutorial sample code onto an IBM Blockchain Platform network. This allows you to
quickly get started interacting with your network and use the sample to download the necessary dependencies. The sample
code also includes examples of how you can import certificates into a wallet and use your connection profile to build a Fabric
gateway. The tutorial can be used by two different organizations to complete different transactions with a single asset. If you
used the Build a network tutorial to deploy two peer organizations that are connected to a channel, you can interact with the
tutorial by using both organizations.
Use the following steps to deploy the sample on your network. You can review the tutorial in the Fabric Documentation
commercial paper tutorial for more details about the smart contracts and the application structure.
Prerequisites
Before you can deploy the commercial paper sample, you need to install required tools on your local machine:
Git
Node.js
You will also need a use text editor to edit and save files in the sample. You can use many of the high-quality editors that are
available for free, such as Visual Studio Code, Atom, Sublime text, or Brackets.
Step one: Download the sample

You download the commercial paper sample by cloning the Fabric Samples repository:
git clone https://github.com/hyperledger/fabric-samples.git
After you download the Fabric Samples, run the following commands to ensure that you are using the version of the samples
compatible with Fabric v1.4.12 and v2.2.5.
cd fabric-samples
git checkout v1.4.9

You can find the sample in the commercial paper folder of fabric-samples .
cd $HOME/fabric-samples/commercial-paper
The tutorial contains two sample organizations, magnetocorp and digibank. Each organization has its own sample application
code, which is stored in two separate folders under the organization directory.
ls organization
digibank magnetocorp
In the course of the tutorial, you will first use the magnetocorp application code to issue a commercial paper. You can then use
the digibank application code to buy and redeem the paper. Both directories contain the same smart contract.
Navigate to the application code inside the magnetocorp directory.
cd organization/magnetocorp/application
When you are inside the directory, you can download the application dependencies by running the following command:
npm install

You can find the commercial paper smart contract inside the contract folder of the digibank and magnetocorp directory.
You need to install this smart contract on all the peers of the organizations that use the tutorial.
Smart contracts running on peers using the Fabric v1.4.x image must be packaged in .cds format. These smart contracts are
installed and then instantiated on a channel. For information on using smart contracts with Fabric v1.4.x peers, check out
Deploy a smart contract using Fabric v1.4.x.
Smart contracts running on peers using a Fabric v2.x image must be packed using the .tar.gz format. These smart contracts
must be installed and proposed by you, then approved by other channel members before being committed on the channel. For
information on using smart contracts with Fabric v2.x peers, check out Deploying a smart contract using Fabric 2.x.
You can use the IBM Blockchain VS code extension to package the smart contract. After you install the extension, use Visual
Studio Code to open the contracts folder in your workspace. Open the IBM Blockchain Platform tab. In the IBM Blockchain
Platform pane, go to the smart contract packages section and clickPackage Open Project. The VS code extension uses the files
in the contracts folder to create a new package named papernet-js@.0.0.1.cds . Right-click this package to export it to
your local file system. You can then use your console to install your smart contract and either instantiate or propose it.
Step three: Generate certificates for your wallet

Applications need to sign the requests they send to Fabric components. If the components do not recognize the organizations
submitting the transactions, the transactions are rejected and return with an error. The commercial paper sample creates a file
system wallet that stores your certificates and signs your transactions. For more information about how applications use wallets,
see the wallet topic in the Fabric Documentation. The wallets that are used by the Fabric SDKs are different from the wallet in
the IBM Blockchain Platform console. The identities that are stored in your console wallet cannot be directly used by the SDK.
The original sample uses the addToWallet.js file to create a file system wallet using certificates from the fabric samples

folder. We are going to create a new file that uses the SDK to generate a client-side certificate and store them directly inside a
new wallet.
Choose the CA of the organization you want to use to operate the tutorial as magnetocorp. For example, you can use Org1 if you
have completed the Build a network tutorial. Use the CA to create an application identity. Save the enroll ID and secret.
Use your console to download your connection profile. Save the connection profile to your local file system and rename it
connection.json . Then, issue the following command from the magnetocorp/application directory to move the
connection profile to a directory where it will be referenced by future commands.
mv $HOME/<path_to_creds>/connection.json ../gateway/connection.json
Save the following code block as enrollUser.js in the /magnetocorp/application directory:
'use strict';

const ccpPath = path.resolve(__dirname, '../gateway/connection.json');

const ccp = JSON.parse(ccpJSON);

try {
// Create a new CA client for interacting with the CA.

const caURL = ccp.certificateAuthorities['<CA_Name>'].url;
const ca = new FabricCAServices(caURL);
// Create a new file system based wallet for managing identities.

const wallet = new FileSystemWallet('../identity/user/isabella/wallet');
// Check to see if we've already enrolled the admin user.

const userExists = await wallet.exists('user1');
if (userExists) {
console.log('An identity for "user1" already exists in the wallet');
return;
}
await wallet.import('user1', identity);
} catch (error) {
console.error(`Failed to enroll "user1": ${error}`);
process.exit(1);
}
}
main();
Take a moment to study how this file works before we edit it. First, enrollUser.js imports the FileSystemWallet and
X509WalletMixin classes from the fabric-network library.


The file then uses the FileSystemWallet class to build a wallet on your local filesystem. You can edit the following line to store
the wallet in a different location.
const wallet = new FileSystemWallet('../identity/user/isabella/wallet')
After you create the wallet, the code snippet uses the enroll ID and secret to enroll by using your organization CA. It then creates
an identity for the signing certificate and private key and imports them into the wallet. Notice how the file passes your
organization MSP ID into the wallet as well.
wallet.import('user1', identity);
Edit enrollUser.js to replace the following values:
Replace <CA_Name> with the name of your organization's CA. You can find your CA name in the "organizations" section of
your connection profile under "Certificate Authorities". Do not use the "caName" in the "Certificate Authorities" section.
Replace <app_enroll_id> with the application enroll ID provided by your network operator.
Replace <app_enroll_secret> with the application enroll secret provided by your network operator.
Replace <msp_id> with the MSP ID of your organization. You can find this MSP ID under the "organizations" section of your
connection profile.
Save enrollUser.js and close it. In the magnetocorp directory, run the following command:
node enrollUser.js
When the command completes successfully, you should see the following output:
$ Successfully enrolled client "user1" and imported it into the wallet
You can find the wallet that was created in the identity folder of the magnetocorp directory.
Step four: Use the connection profile to build a Fabric gateway

The Hyperledger Fabric Transaction Flow spans multiple components, with the client applications playing a unique role. Your
application needs to connect to the peers that need to endorse the transaction and needs to connect to the ordering service that
will order the transaction and add it into a block. You can provide the endpoints of these nodes to your application by using your
connection profile to construct a Fabric gateway. The gateway then conducts the low-level interactions with your Fabric network.
To learn more, visit the Fabric gateway topic in the Fabric documentation.
You have already downloaded your connection profile and used it to connect to your organization's Certificate Authority. Now we
use the connection profile to build a gateway.
Open the file issue.js in a text editor. Before you edit the file, notice that it imports the FileSystemWallet and Gateway
classes from fabric-network library.
const { FileSystemWallet, Gateway } = require('fabric-network')
You will need to import the path class to build the gateway from the connection profile you downloaded from your console.Add
the following line to the file to import the path class:

The Gateway class is used to construct a gateway that you will use to submit your transaction.
const gateway = new Gateway()
The FileSystemWallet class is used to load the wallet you created in the previous step. Edit the following line if you changed
the location of the wallet on your file system.
const wallet = new FileSystemWallet('../identity/user/isabella/wallet');
After you import your wallet, use the following code to pass your connection profile and wallet to the new gateway. You need to
make the following Edits to the code so it resembles the code snippet below. The lines that print logs have been removed for
brevity.
Update the userName to match the value that you selected for your identityLabel in enrollUser.js.
Update the discovery options to take advantage of service discovery on your network. Setdiscovery: { enabled:
true, asLocalhost: false, strategy: DefaultQueryHandlerStrategies.MSPID_SCOPE_ROUND_ROBIN }.
Update the section importing your connection profile. The console connection profile is in JSON format rather than a YAML
file used by the sample.
const userName = 'user1';
// Load connection profile; will be used to locate a gateway

const ccpPath = path.resolve(__dirname, '../gateway/connection.json');
const connectionProfile = JSON.parse(ccpJSON);
// Set connection options; identity and wallet

let connectionOptions = {
identity: userName,
wallet: wallet,
discovery: { enabled: true, asLocalhost: false, strategy:
DefaultQueryHandlerStrategies.MSPID_SCOPE_ROUND_ROBIN }
};
await gateway.connect(connectionProfile, connectionOptions);
This code snippet uses the gateway to open gRPC connections to the peer and orderer nodes, and interact with your network.
Enabling service discovery

Fabric service discovery allows your applications to dynamically find the peer and ordering endpoints of your network and the
peers on the channel outside your organization that need to endorse a transaction. If you do not configure service discovery, the
endpoint information of peer and ordering nodes on your channel needs to be added manually to your connection profile or your
application. You would need to edit your connection profile or update your application each time a node is added or removed
from your network.
To configure a client application to use service discovery, set the following options on the gateway.connect() call by defining
connectionOptions that include:
$ discovery: { enabled: true, asLocalhost: false, strategy:

DefaultQueryHandlerStrategies.MSPID_SCOPE_ROUND_ROBIN }
Setting strategy: DefaultQueryHandlerStrategies.MSPID_SCOPE_ROUND_ROBIN ensures that requests from the client

application are distributed across available peers. See DefaultQueryHandlerStrategies in the Node SDK documentation for more
information.
Step five: Invoke the smart contract

After you configure the gateway to connect to the network managed by your console, we will edit the portion of the issue.js
file that connects to the commercial paper smart contract. You need to provide the gateway the contract name and the channel
where the smart contract was deployed.
Edit the following line, and replace mychannel with your channel name.
const network = await gateway.getNetwork('mychannel');
Following a line of code that prints a message to your console, you can find a line that provides the gateway the smart contract
name. Edit the following line to change the name papercontract to the name of the contract you installed.
const contract = await network.getContract('papercontract', 'org.papernet.commercialpaper');
The gateway now has all the information that it needs to submit a transaction. The following line invokes theissue function in
the commercial paper contract, with the arguments defining the new commercial paper asset.
const issueResponse = await contract.submitTransaction('issue', 'MagnetoCorp', '00001', '2020-05-31',

'2020-11-30', '5000000');
After it submits the transaction using the gateway, the issue.js file disconnects the gateway connection.
gateway.disconnect();
This command closes the gRPC connections opened by your gateway. Closing connections save network resources and improve
performance.
After completing the edits from this step and Step four, save issue.js and close it. Submit the transaction that creates the
new commercial paper by using the following command:
node issue.js
If the transaction is successful, you can see the following output in your terminal:
$ Transaction complete.
Disconnect from Fabric gateway.
Issue program complete.
Step six: Operate the sample as Digibank

After you create the commercial paper by operating as Magnetocorp, you can buy and redeem the commercial paper by
operating the tutorial as Digibank. You can use the Digibank application code by using the same organization as Magnetocorp, or
use the CA, peers, and connection profile of a different organization. If you competed the Join a network tutorial, this is a good
opportunity operate the tutorial as Org2.
Go to the digibank/application directory. You can follow the directions that are provided inStep three to create to generate
the certificates and wallet that will sign the transaction as Digibank. You can then use the buy.js file to purchase the
commercial paper from Magnetocorp, and then use redeem.js to redeem the paper. You can follow Step four and Step five to
edit those files so that they point to the correct connection profile, channel and smart contract.
Connecting to your network by using low-level Fabric SDK APIs

If you are interested in preserving your existing application code, or by using Fabric SDKs for languages other than Node.js, you
can still connect to your network by using lower-level Fabric SDK APIs. Use the console to download your connection profile.
You can then import the endpoints of the peers and ordering nodes of your channel directly from the connection profile, or use

the node endpoint information to manually add peer and orderer objects. You will also need to use your CA to create an
application identity, and then use the CA endpoint information enroll on the client side, or generate certificates using your
console.
The Fabric Node SDK documentation provides a tutorial on how to connect to your network using a connection profile. The
tutorial uses the CA endpoint information in your connection profile to generate keys using the SDK. You can also use your
console to generate a signing certificate and private key and convert the keys into PEM format. You can then set a user context
by passing your keys directly to the SDKs' Fabric Client class using the following code:
fabric_client.createUser({
username: 'admin',
mspid: 'org1',
cryptoContent: {
privateKeyPEM: fs.readFileSync(path.join(__dirname,'./privateKey.pem')),
signedCertPEM: fs.readFileSync(path.join(__dirname,'./certificate.pem'))
}});
If you are using low-level SDK APIs to connect to your network, there are additional steps that you can take to manage the
performance and availability of your application.
Highly available applications

As a high availability best practice, it is strongly recommended that you deploy a minimum of two peers per organization for
failover. You need to adapt your applications for high availability as well by downloading a connection profile and enabling
service discovery. Install smart contracts on both peers and join the peers to your channels.
Using indexes with CouchDB

If you use CouchDB as your state database, you can perform JSON data queries from your smart contract against the channel's
state data. It is strongly recommended that you create indexes for your JSON queries and use them in your smart contract.
Indexes allow your applications to retrieve data efficiently when your network adds additional blocks of transactions and entries
in the world state.
For more information about CouchDB and how to set up indexes, see CouchDB as the State Database in the Hyperledger Fabric
documentation. You can also find an example that uses an index with chaincode in the Fabric CouchDB tutorial.
Avoid using chaincode for queries that will result in a scan of the entire CouchDB database. Full length database scans result in
long response times and will degrade the performance of your network. You can take some of the following steps to avoid and
manage large queries:
Set up indexes with your chaincode.

All fields in the index must also be in the selector or sort sections of your query for the index to be used.
More complex queries will have a lower performance and will be less likely to use an index.
You should try to avoid operators that will result in a full table scan or a full index scan, such as$or, $in , and $regex.
You can find examples that demonstrate how queries use indexes and what type of queries will have the best performance in the
Fabric CouchDB tutorial.
Peers on the IBM Blockchain Platform have a set queryLimit, and will only return 10,000 entries from the state database. If your
query reaches the queryLimit, you can use multiple queries to get the remaining results. If you need more results from a range
query, start subsequent queries with the last key that is returned by the previous query. If you need more results from JSON
queries, sort your query by using one of the variables in your data, then use the last value from the previous query in a 'greater
than' filter for the next query.
Do not query the entire database for the purpose of aggregation or reporting. If you want to build a dashboard or collect large

amounts of data as part of your application, you can query an off chain database that replicates the data from your blockchain
network. This allows you to understand the data on the blockchain without degrading the performance of your network or
disrupting transactions.
You can use block or chaincode events from your application to write transaction data to an off-chain database or analytics
engine. For each block received, the block listener application would iterate through the block transactions and build a data
store by using the key/value writes from each valid transaction's rwset . The Peer channel-based event services provide
replayable events to ensure the integrity of downstream data stores. For an example of how you can use an event listener to
write data to an external database, see the Off chain data sample in the Fabric Samples.
Clock synchronization
Synchronizing your application with a Network Time Protocol (NTP) server is important because it ensures that all time-based
activities occur synchronously everywhere on the network. NTP is widely used to synchronize a computer to Internet time
servers or other sources. The IBM Blockchain Platform runs in IBM Cloud and uses an internal NTP server
servertime.service.softlayer.com .
The NTP server that you need to synchronize your application with depends on where your application is running:
If your application is running in IBM Cloud Classic infrastructure, set your NTP server to
servertime.service.softlayer.com.
If your application is running in IBM Cloud VPC infrastructure, set your NTP server totime.adn.networklayer.com.
If your application is not running in IBM Cloud, set your NTP server totime-a.nist.gov or time-b.nist.gov.
Additional Resources
IBM Developer
For tutorials, code patterns, and videos that help developers get started and learn best practices for developing blockchain
applications.
Blockchain Design Patterns

For application developers who want to learn about common patterns for interacting with blockchain networks.

Certificate Authority (CA) options
Creating an intermediate Certificate Authority (CA)
For customers who prefer to include intermediate CAs in their network, the IBM® Blockchain Platform offers this configuration
option when you deploy a CA. This tutorial describes the process for creating an intermediate CA.
Why would I want to use an intermediate CA with my IBM Blockchain Platform network?
Intermediate CAs are optional. Because an intermediate CA has its root certificate issued by a root CA or another intermediate
authority, a “chain of trust” is established for any certificate that is issued by all CAs in the chain. Having one or more
intermediate CAs provides added security and allows you to protect your root of trust. This ability to track back to the root CA
not only allows the function of CAs to scale while still providing security, it also limits the exposure of the root CA, which, if
compromised, would endanger the entire chain of trust. If an intermediate CA is compromised, on the other hand, there will be a
much smaller exposure. A key benefit is that after the intermediate CAs are up and running, the root CA can be effectively turned
off, limiting its vulnerability even more.
Another reason to include an intermediate CA would be when you have a very large organization with multiple departments and
you don’t want a single CA to generate certificates for all of the departments. Intermediate CAs provide a mechanism for scoping
the certificates that a CA manages to a smaller department or sub-group. This pattern though incurs significant increase if there
will only be a small number of members in the organization.
As an alternative to deploying multiple intermediate CAs, you can limit the scope of a CA by overriding the CA configuration to
specify available affiliations (similar to departments) instead. When a CA is configured with affiliations, the affiliation of the
registrar must be equal to or a prefix of the affiliation of the identity being registered. See the Fabric CA topic on registering
identities for more details.
The following diagram illustrates how the root CA issues the certificates for the intermediate CA and the intermediate CA then
issues the certificates for the nodes and users in the organization.
Figure 1. Intermediate CA in the network.
Can I convert an existing CA to be an intermediate CA?

No. Because the CA signed certificate cannot be regenerated, you cannot convert an existing CA to become an intermediate CA.
If you did, all of the existing certificates that were issued by the CA would no longer be valid. Therefore, if you want to have an
intermediate CA in your network, you need to create a new CA and configure it to be an intermediate CA during the deployment
process.
Limitations
Currently, IBM Blockchain Platform only supports a single level of intermediate CAs. In other words, an intermediate CA cannot
be a parent server to another intermediate CA.
Process overview
The configuration process begins with the root CA. If one does not already exist, you need to create the root CA and then register
two identities that are needed by the intermediate CA. When you create an intermediate CA you need to provide a JSON that
overrides the default CA settings with the intermediate CA configuration. After your intermediate CA is active, you can use it for
all subsequent identity register and enrollment requests for the organization, and then effectively turn off the root CA. At a high
level, the following steps need to be performed:

Part One: Actions you perform from the root CA
1. Deploy a root CA if one does not already exist.

2. Register the intermediate CA admin identity with the root CA.
3. Register the intermediate TLS CA admin identity with the root CA.
4. Export the root CA to a JSON file.
Part Two: Build the intermediate CA JSON override
Edit the example JSON override file by providing the root CA TLS signing cert and the intermediate CA identity enroll id and
secrets to the JSON override file.
Part Three: Actions you perform on the intermediate CA
1. Create a new CA which will serve as the intermediate CA.

2. Provide the intermediate CA admin enroll ID and secret that you registered with the root CA.
3. Provide the CA JSON override file.
After completing these steps, when you create organization MSPs for your peers or orderers, you can point to the intermediate
CA instead of the root CA.
Note: This process can be performed using the console or the APIs, if you are an experienced API user. The overall
process is the same regardless of which approach you choose. For clarity, this tutorial uses the console.

1. Deploy a root CA. Before you can deploy an intermediate CA, a root CA must already exist in your IBM Blockchain
instance. See the Build a network tutorial for instructions on how to create a CA.
2. Register the intermediate CA admin identity with the root CA. In order for an intermediate CA to be able to register and
enroll identities, the intermediate CA admin identity must be registered with the root CA.
Click the root CA tile to open it and clickRegister user.

Enter the enroll ID and secret that you will use for the intermediate CA admin identity. For purposes of this tutorial
we will use icaadmin and icaadminpw, but you can use any values suitable for your use case.
Leave the identity type as client and optionally specify a value for maximum enrollments if you want to limit the
number of times you can generate certificates for this admin identity. Otherwise, you can leave it blank.
On the next panel, because this identity will be for the intermediate CA admin, you need to add the attribute
hf.IntermediateCA and set its value to true. Don't forget to click Add.
Click Register user when you are finished.
3. Register the intermediate TLS CA admin identity with the root CA. Because TLS communications are enabled on the
network, whenever you deploy a CA, a TLS CA is automatically deployed along side the CA, and uses the same endpoint
address. Therefore, you also need to register an identity that will serve as the intermediate TLS CA admin. Repeat the
actions that you performed in the previous step to register the admin identity, but this time specify a different enroll ID and
secret. For purposes of the tutorial, we use itlscaadmin and itlscaadminpw .
4. Export the root CA to a JSON file. Now that you have the intermediate CA admins registered with the root CA, there is one
last piece of information we need: the root CA TLS signed certificate. This certificate is shared with each node in the
organization and is used to secure the communications between the nodes. Therefore, in order for the intermediate CA to
communicate with the root CA, it has to be included in the intermediate CA configuration. To get the root CA TLS signed
certificate, simply export the root CA to a JSON file. Open the root CA and click the Export icon.

Figure 2. Export root CA
Open the downloaded JSON file and locate the value corresponding to the tls_cert element. You will need to
copy and paste the certificate in a later step. It will resemble:
$
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQWtXZ0F3SUJBZ0lRWXZYRUgzUktMUVNiUnZTdnRLWU
JDVEFLQmdncWhrak9QUVFEQWpDQnB6RUwKTUFrR0ExVUVCaE1DVlZNeEZ6QVZCZ05WQkFnVERrNXZjblJvSUVOaGNtO
XNhVzVoTVE4d0RRWURWUVFIRXdaRQpkWEpvWVcweEREQUtCZ05WQkFvVEEwbENUVEVUTUJFR0ExVUJVaHAKVkM1VE5O
VzNqRzJkVVZwUUlkSmEvMWtDSVFEMGE0QWRzazJ0RlhDRFp1RFB0VG5lTkNZWnBDSzMxL2MrUTFLTQozLzVGdEE9PQo
tLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCga1",
Also make note of the value of the api_url in the JSON file. You will use the value of this URL to build the parent
server URL for the intermediate CA. It will resemble:
$ "api_url": "https://nb535a5-rootca.org1Cluster.us-south.containers.appdomain.cloud:7054",
To build the parent server URL, edit the URL and insert the intermediate CA admin enroll ID and secret using the
following format:
$ https://<INTERMEDIATE-CA-ADMIN>:<INTERMEDIATE-CA-ADMIN-PW>@<DOMAIN>:<PORT>
For example:
$ https://icaadmin:icaadminpw@nb535a5-rootca.org1Cluster.us-
south.containers.appdomain.cloud:7054
Save the value of this URL for the next section.

Anytime that you deploy a CA, you can override the default CA settings by pasting a JSON that contains the parameters that you
want to override. Because we are deploying an intermediate CA, we need to override some of the default settings in order to
configure it to be an intermediate CA. For example, you need to configure the intermediate block of the JSON to point to your
root CA as the parent server. Therefore, copy the following text to an editor where you can modify the values:
{
"ca": {
"debug": true,
"registry": {
"maxenrollments": -1,
"identities": [{
"name": "<INTERMEDIATE-CA-ADMIN>",
"pass": "<INTERMEDIATE-CA-ADMIN-PW>",
"type": "client",
"attrs": {
"hf.Registrar.Roles": "*",
"hf.Registrar.DelegateRoles": "*",

"hf.Revoker": true,
"hf.IntermediateCA": true,
"hf.GenCRL": true,
"hf.Registrar.Attributes": "*",
"hf.AffiliationMgr": true
}
}]
},
"intermediate": {
"parentserver": {
"url": "<PARENT-CA-SERVER-URL>",
"caname": "ca"
},
"tls": {
"enabled": true,
"certfiles": ["<TLS-CERT-FILE>"]
}
}
},
"tlsca": {
"debug": true,
"registry": {
"identities": [{
"name": "<INTERMEDIATE-TLS-CA-ADMIN>",
"pass": "<INTERMEDIATE-TLS-CA-ADMIN-PW>",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "<PARENT-TLS-CA-SERVER-URL>",
"caname": "tlsca"
},
"tls": {
"enabled": true,
}
}
}
}
Notice there are settings for both the intermediate CA and the intermediate TLS CA. Replace the following parameters:
<INTERMEDIATE-CA-ADMIN> - with the enroll ID that you specified in Part One, step 2 when you registered the
intermediate CA admin identity.
<INTERMEDIATE-CA-ADMIN-PW> - with the enroll secret that you specified in Part One, step 2 when you registered the
<PARENT-CA-SERVER-URL> - with the value of the parent server that you built in Part One, step 4.
<TLS-CERT-FILE> - (two occurrences) with the value of the tls_cert, the certificate string that you downloaded from the
root CA in Part One, step 4.
<INTERMEDIATE-TLS-CA-ADMIN> - with the enroll ID that you specified in Part One, step 3 when you registered the
intermediate TLS CA admin identity.
<INTERMEDIATE-TLS-CA-ADMIN-PW> - with the enroll secret that you specified in Part One, step 3 when you registered
the intermediate TLS CA admin identity.
<PARENT-TLS-CA-SERVER-URL> - with the value of the parent server URL that you built in Part One, step 4; however you
need to replace the enroll ID and secret with the values that you specified when you registered the admin for the

intermediate TLS CA, in Part One, step 3. Because both the intermediate CA and intermediate TLS CA are deployed to the
same endpoint address, the rest of the URL remains the same as the <PARENT-CA-SERVER-URL>.
Your completed JSON looks similar to:
$ {
"ca": {
"debug": true,
"registry": {
"identities": [{
"name": "icaadmin",
"pass": "icaadminpw",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "https://icaadmin:icaadminpw@nb535a5-rootca.org1Cluster.us-
south.containers.appdomain.cloud:7054",
"caname": "ca"
},
"tls": {
"enabled": true,
"certfiles":
["LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQWtXZ0F3SUJBZ0lRWXZYRUgzUktMUVNiUnZTdnRLWUJDVEFLQmdncWhrak9QUVFEQW
}
}
},
"tlsca": {
"debug": true,
"registry": {
"identities": [{
"name": "itlscaadmin",
"pass": "itlscaadminpw",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "https://itlscaadmin:itlscaadminpw@nb535a5-rootca.org1Cluster.us-
"caname": "tlsca"
},
"tls": {
"enabled": true,
"certfiles":

}
}
}
}

You've registered the intermediate CA and intermediate TLS CA identities with the root CA and have built the JSON for the CA
override. You are now ready to deploy the intermediate CA.
1. From the Nodes tab, click Add Certificate Authority followed by Create a Certificate Authority.
2. Give your intermediate CA a meaningful name and then provide the intermediate CA admin enroll ID and secret that you
registered with the root CA. For example icaadmin and icaadminpw. You can leave the Advanced deployment options
deselected, none are required for an intermediate CA.
3. On the Summary panel, click Edit configuration JSON (Advanced).
4. Delete the existing content from the Configuration JSON box and paste the JSON that you built in Part Two, then click
Add Certificate Authority.
Tip: It will take a few minutes for the CA to deploy. You'll know it is ready when a green status indicator box is visible on
the tile. Depending on your cluster activity, you might need to refresh your browser for the status to turn green.
Next steps
Register and enroll identities against the intermediate CA

Your intermediate CA is now operational and can be used to register and enroll identities just like you do with the root CA. See
the topic on Creating and managing identities to learn more.
Create organization MSPs using the intermediate CA

When you build organization MSP definitions for your peer or ordering nodes, you can now reference the intermediate CA as the
"root CA" instead of your root CA.
Figure 3. MSP using intermediate CA
If you want to learn more about creating MSPs, see Managing organizations.

Scale down the root CA
Because the intermediate CA can process all requests that the root CA handles, you can effectively turn off your root CA by
scaling down the root CA CPU to 0.001 CPU. Taking this action renders the root CA non-functional while in this state. As long as
you don't need the root CA to issue identities or enroll other intermediate CAs, it can be safely scaled down. See the topic on
Reallocating resources for the steps to scale down the CPU. If the root CA is needed later, for example to enroll another
intermediate CA, you can always repeat the steps to scale back up the CPU. The minimum CPU required for a CA to be
operational is 0.1 CPU .
By default, certificates generated by IBM Blockchain Platform CAs expire after one year and peer and ordering node TLS
certificates expire after 15 years. Exactly thirty days before peer and ordering node certificates are due to expire, the platform
automatically attempts to contact the CA and renew the certificates. If the CA is not online, the automatic renewal fails and
enrollment to generate a new certificate needs to be performed manually. If automatic renewal of these certificates is important
for your business, careful consideration should be given to scaling down a root CA or intermediate CA. See the topic on
Certificate expiration and renewal to learn more about the process.
Using certificates from an external Certificate Authority

In this tutorial, you learn how to use certificates that were generated by an external Certificate Authority (CA) with your IBM®
Blockchain Platform network. After you gather the required certificates for a peer or ordering node, you build a Membership
Service Provider (MSP) definition that is used by your blockchain components.
While it is always possible to use a CA that you create with the console to generate identities, you can also use certificates that
were generated by a CA external to your network, one that is not hosted by IBM, and then build the required organization
Membership Service Provider (MSP) definition that is used by your blockchain components.
Objectives
Gather certificates.
Build MSP definition.
Import MSP into the console.
Create and import the organization admin identity to the wallet.
Deploy a blockchain node.
Before you begin

Install the IBM® Blockchain Platform.
Step 1: Gather certificates

You need to request the following set of certificates from the external CA in X.509 format. When you request the certificates
from your provider, the core requirement for the certificates is that they are ECDSA with Curve P256 and that the private key
uses the PKCS #8 standard. Also when you request the certificates, you need to specify a Node Organizational Unit (OU)
attribute for some certificates as indicated in the Node OU column in the following tables. Certificates can be in the format of a
.pem file or a base64 encoded string.
When you create a peer or ordering node, you need to provide the following four certificates in PEM format. When you request
these certificates from the third-party CA, you need to request a specific Node Organizational Unit (OU) attribute for some
certificates as indicated in the Node OU column.
Node Description Node OU Format

certificates

1. Peer or The public certificate of the node’s identity. "peer" or PEM
ordering "orderer"
node depending
identity on the
certificate node type
2. Peer or The private key corresponding to the public signing certificate. Make sure to keep PEM
ordering this certificate safe, as it can be used to impersonate the node.
node
identity
private
key
3. Peer or The public signing certificate created by your external TLS CA that is used by the PEM
ordering peer or ordering node. The certificate needs to contain the x.509 Subject
service alternative name (SAN) for the peer or ordering nodes. If you are using the Fabric
TLS CA CA client to enroll the identity, you specify the SAN by passing the--csr.hosts
certificate parameter on the enroll command. If the hostname is not yet known, you can
specify a wildcard with the domain name, for example: --csr.hosts '*.ibpv2-
cluster.us-south.containers.appdomain.cloud,127.0.0.1'.
4.Peer or The private key corresponding to the signed certificate from your TLS CA that is PEM
ordering used by the peer or ordering node for secure communications with other members
service on the network.
TLS CA
private
key
Table 1. Node certificates
MSP certificates Description Node OU Format
1. CA root The root certificate of your external CA. You can also provide an base64
certificate intermediate CA root certificate or both.
2. TLS CA root The root certificate of your external TLS CA. You must provide either a TLS base64
certificate CA root certificate or an intermediate TLS CA certificate, you can also
provide both.
3. Intermediate The root certificate of your intermediate CA. You must provide either a CA base64
CA root root certificate or an intermediate CA root certificate, you can also provide
certificate: both.
(Optional)
4. Intermediate The TLS certificate if your TLS certificate is issued by an intermediate TLS base64
CA TLS certificate: CA. Upload the intermediate TLS CA certificate. You must provide either a
(Optional) TLS CA root certificate or an intermediate TLS CA certificate, you may also
provide both.
5. Peer or ordering The signing certificate from your external CA that the admin identity of this "admin" base64
organization peer or ordering service uses.
admin identity
certificate
6. Peer or ordering The private key corresponding to the signed certificate from your external base64
organization CA that the admin identity of this peer or ordering service uses.
admin identity
private key
Table 2. MSP certificates
Consideration when using an external CA to generate certificates

If a generated private key is in PKCS #1 format, before it can be used by the console, it needs to be converted to PKCS #8
format by running the following openssl command:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in identity.1.pem -out identity.8.pem
Replace:
identity.1.pem with the name of the PKCS #1 private key .PEM file.
identity.8.pem with the name that you want to give your PKCS #8 private key.PEM file.
Step 2: Build MSP definition

An MSP definition is the mechanism that allows other members of the blockchain consortium to verify the identity of your nodes
and applications. Because MSPs define an organization, they are required when you create channels, create nodes (to identify
which organization the node belongs to), and validate signatures.
The MSP definition requires that all certificates are encoded in base64 format. If needed, you can convert the contents of a
certificate file, <cert.pem> from PEM format into a base64 string by running the following command on your local machine:
cat <cert.pem> | base64 $FLAG
To build the MSP definition, create a JSON by copying the following text and saving it to a file of type JSON:
{
"name": "<organization_name>",
"display_name": "<organization_name>",
"msp_id": "<organization_id>",
"type": "msp",
"admins": [
"<admins>"
],
"root_certs": [
"<root_certs>"
],
"tls_root_certs": [
"<tls_root_certs>"
],
"fabric_node_ous": {
"enable": true,
"admin_ou_identifier": {
"certificate": "<ou_root_cert>",
"organizational_unit_identifier": "admin"
},
"client_ou_identifier": {
"organizational_unit_identifier": "client"
},
"orderer_ou_identifier": {
"organizational_unit_identifier": "orderer"
},
"peer_ou_identifier": {
"organizational_unit_identifier": "peer"
}
},
"host_url": "<url>",
}
Replace the following values:
organization_name: Specify any name to be used to identify this MSP definition in the console.
organization_id: Specify an ID that is used to represent this MSP internally in the console.
root_certs: Paste in an array that contains one or more root certificates from the external CA inbase64 format. You must

provide either a CA root certificate or an intermediate CA certificate. You can also provide both. This is certificates 1 and 3
in the MSP certificates table.
admins: Paste in the signing certificate of the organization admin identity in base64 format. This is certificate 5 in the MSP
certificates table.
tls_root_certs: Paste in an array that contains one or more root certificates from the TLS CA inbase64 format. You must
provide either an external TLS CA root certificate or an external intermediate TLS CA certificate, you can also provide both.
This is certificate 2 in the MSP certificates table.
ou_root_cert: Specify the trusted CA root certificate for each role. Typically this value would be the same as the
root_certs. This is certificate 1 in the MSP certificates table.
host_url: Specify the URL of the blockchain console where this MSP collects signatures. This is the URL from your browser
minus /nodes. For example, from the Nodes tab, the browser URL is similar to https://d0ddb7-
optools.uss02.blockchain.cloud.ibm.com/nodes. Therefore the host_url would be https://d0ddb7-
optools.uss02.blockchain.cloud.ibm.com.
fabric_node_OUs: Fabric-specific Organization Units (OUs) that enable identity classification. NodeOUs contain
information for how to distinguish clients, peers, and orderers based on their OU. If the check is enforced, by setting
Enabled to true, the MSP considers an identity valid only if it is an identity of type client, a peer, an admin, or an orderer.
An identity should have only one of these special OUs, which are assigned to an identity when it is registered with the CA.
See this topic for an example of how to specify the fabric_node_OU in an MSP in the Fabric Service Discovery
documentation. Or learn more about using Node OUs in Fabric.
The following additional fields are also available in your MSP definition but are not required:
intermediate_certs: (if an intermediate CA was used) Paste in an array that contains one or more certificates from the
external intermediate CA in base64 format. You must provide either a CA root certificate or an intermediate CA certificate,
you can also provide both.
tls_intermediate_certs: (if an intermediate TLS CA was used) Paste in an array that contains one or more certificates from
the intermediate TLS CA in base64 format. You must provide either an external TLS CA root certificate or an external
intermediate TLS CA certificate, you can also provide both.
organizational_unit_identifiers: A list of Organizational Units (OU) that valid members of this MSP should include in their
X.509 certificate. This is an optional configuration parameter that is used when multiple organizations leverage the same
root of trust and intermediate CAs, and they have reserved an OU field for their members. An organization is often divided
up into multiple organizational units (OUs), each of which has a certain set of responsibilities. For example, the ORG1
organization might have both ORG1-MANUFACTURING and ORG1-DISTRIBUTION OUs to reflect these separate lines of
business. When a CA issues X.509 certificates, the OU field in the certificate specifies the line of business to which the
identity belongs. See this topic in the Fabric documentation on Identity Classification for more information.
revocation_list: A list of certificates that are no longer valid. For X.509-based identities, these identifiers are pairs of
strings that are known as Subject Key Identifier (SKI) and Authority Key Identifier (AKI), and are checked whenever the
X.509 certificate is being used to make sure that the certificate has not been revoked. See this topic in the Fabric
documentation for more information about Certificate Revocation Lists.
This is an example MSP JSON file:
{
"name": "org1msp",
"display_name": "org1msp",
"msp_id": "org1msp",
"type": "msp",
"admins": [
"LS0tLS1CRUd...LS0tLQo="
],
"root_certs": [
"LS0tLS1CRUd...LS0tLS0K"
],
"intermediate_certs": [],
"tls_root_certs": [
"LS0tLS1CRUd...LS0y=g"
],
"tls_intermediate_certs": [],
"certificate": "LS0tLS1CRUd...LS0tLS0K",
},

},
"enable": true,
},
}
},
"host_url": "https://ibpconsole-console.0defdaa0c51eab4bf04a1-0000.us-
}
Step 3: Import MSP into the console

You have gathered your certificates and built your MSP. Before you can deploy a peer or ordering node, you need to import the
MSP JSON file into your IBM Blockchain Platform console.
1. Navigate to the Organizations tab and click Import MSP.

2. Browse to the MSP JSON file and click Add file.
3. Click Import MSP.
Step 4: Create and import the organization admin identity to the wallet
To be able to act as an administrator for an organization, import the identity that is listed in the MSP JSON "admins" section
into your console wallet, including both the public and private key. When you subsequently deploy a peer or ordering node, you
can designate this identity to be the node admin.
1. To import the identity, open the Wallet tab and click Add identity.
2. Give the identity a name.
3. Click Add certificate and browse to the .pem files for the organization admin identity certificate and private key.
Step 5: Deploy a blockchain node

You've gathered all the certificates, created and imported the MSP, and imported the organization admin identity, you are now
ready to deploy a peer or ordering node. The process to deploy a peer and ordering node is slightly different:
Deploy peer
1. From the Nodes tab, click Add peer > Create peer.
2. Provide a name for your peer.
3. Under Advanced deployment options, check Use your own CA certificate and private key and click Next.
4. In the Certificate field, click Add certificate and browse to the peer enrollment certificate .pem file. This is certificate 1 in
the Node certificates table.
5. In the Private key field, click Add certificate and browse to the peer enrollment private key .pem file. This is certificate 2
in the Node certificates table.
6. In the MSP drop-down list, select the MSP that you imported into the console.
7. Select a Fabric version for your peer and click Next.
8. Provide the TLS certificate and key for the node. In theCertificate field, click Add certificate and browse to the peer TLS
certificate .pem file. This is certificate 3 in the Node certificates table.
9. In the Private key field, click Add certificate and browse to the peer TLS private key.pem file. This is certificate 4 in the
Node certificates table. Click Next.
10. From the Peer administrator identity drop-down list, select the organization admin identity that you imported into the

wallet.
11. Review the details on the Summary panel and click Add peer.
Deploy ordering service

1. From the Nodes tab, click Add ordering service > Create ordering service.
2. Provide a name for your ordering service and select the number of ordering nodes that you want to deploy.
10. From the Orderer administrator identity drop-down list, select the organization admin identity that you imported into
the wallet.
11. Review the details on the Summary panel and click Add ordering service.
Note: Instead of creating an ordering service, if you prefer to contribute a single ordering node to an existing Raft ordering
service, open the ordering service and click the Ordering nodes tab. Click Add ordering node, give it a name then and
following the preceding steps.
It takes several minutes for peer and ordering node deployment to complete. When it is successful, you can see a green box on
the node tile in the console. You might need to refresh your browser for the box to turn from gray to green.
Next steps
Your blockchain nodes are ready to be used on the network. In order for the peer to participate on the network, the peer
organization needs to be part of a consortium on an ordering service so that the peer can join a channel.

2. Scroll down to the ordering service and click the tile to open it.
4. From the drop-down list, select the MSP that you imported into the console.
You can now install smart contracts on your peer and join it to an existing channel.

IBM Cloud Hardware Security Module (HSM)
IBM Cloud includes an HSM service that provides cryptographic processing for key generation, encryption, decryption, and key
storage. This document describes how to use that service with the IBM® Blockchain Platform.
While this tutorial focuses specifically on using IBM Cloud HSM, you can learn more about the overall configuration process for
using any HSM that supports PCKS #11 with the IBM Blockchain Platform, see Configuring a node to use a Hardware Security
Module.
Why would I want to use an HSM with my IBM Blockchain Platform network?
When a Certificate Authority (CA), peer, or ordering node is configured to use an HSM, their private key is generated by and
protected inside a tamper resistant HSM device. IBM Cloud HSM is a FIPS 140-2 Level 3 validated, single-tenant device that
implements Gemalto (Luna) HSM. When a CA is configured to use HSM, the CA root private key is stored in the HSM. This is the
key that is used to sign enrollment requests. After a peer or ordering node is configured to use HSM, the nodes are able to sign
and endorse transactions without ever exposing their private key.
Important: Because only the private keys of node identities are secured in the HSM, when you enroll other admin or
client application identities with a CA, their private keys are not stored inside the HSM because they will need their private
key to transact on the network.
Using IBM Cloud HSM

IBM Cloud HSM 6.0 and 7.0 are available in the IBM Cloud catalog. Both versions are supported, however, these instructions
focus on how to configure IBM Cloud HSM 6.0 to work with the IBM Blockchain Platform. If you are using 7.0, it is possible that
some of the commands will differ slightly.
Process overview
Part One: Set up the HSM device and HSM client
This process involves deploying an HSM and configuring a partition as well as deploying an HSM client that you will use to
configure the device. Throughout these instructions you will run some commands from the HSM server and others from
the HSM client. For clarity, we prefix these steps with either or .
Part Two: Configure communications between the HSM server and client
Communications between the HSM and client require a Network Trust Link (NTL) -- an encrypted, secure communications
channel between the HSM and client. NTL uses digital certificates that the client and HSM server can use to verify each
other's identity. You will run a command to get the HSM server certificate that allows the client to communicate with the
HSM server. Likewise, you will generate a certificate and private key for the client and then copy them to the HSM server.
Part Three: Register the client with the HSM server
After the secure communications are configured, you can register the client with the HSM server and then assign the HSM
partition to the client.
Part Four: Build a Docker image
Build an HSM Client image

This process requires Docker to be installed on the machine where the HSM client is running and that you are familiar with the
process for building Docker images. It also presumes you are comfortable with using the Kubernetes CLI to administer your
Kubernetes cluster.
If you are using a Kubernetes cluster on IBM Cloud and IBM Cloud HSM, both services need to be deployed from the same IBM
Cloud account and on the same VLAN. If they are not on the same VLAN, then VLAN spanning must be enabled.
When the entire HSM configuration is complete, it resembles the following diagram:
HSM configured with an HSM client image
Figure 1. An example configuration of an HSM configured with an HSM client image.
The steps in this topic focus specifically on the creation of the Cloud HSM and the HSM Client in the diagram. When you deploy a
CA, peer, or ordering node to use the HSM, you need to provide the label and PIN of the HSM partition. This configuration
assumes you enabled HSM on your Kubernetes cluster when you deployed the service.

1. Provision the HSM and configure it with at least one partition. For example, you can follow instructions for Provisioning
IBM Cloud HSM.
Important: Be sure to record the Label and PIN for the partition. You will need to provide these values later when
you configure a blockchain node to use this HSM partition. Also, save the IP address associated with the HSM
device. We will refer to this value throughout these instructions as <HSM_ADDRESS> .
2. Install the HSM client on your local machine. Make sure the client version that you are running matches the HSM server
version. Record the IP address or fully qualified host name where the HSM client is running. We will refer to this value
throughout these instructions as <CLIENT_ADDRESS> .
Tip: The client runs on AIX, Linux, Oracle Solaris, or Microsoft Windows, but is not supported on MacOS.
In this section you will get the HSM server certificate and create the HSM client certificate-key pair in order for them to be
exchanged.
1. Run the following command using the HSM client to get the server certificate. This certificate enables the client to
communicate with the server.
scp hsm_admin@<HSM_ADDRESS>:server.pem server.pem
Replace
<HSM_ADDRESS> with the IP address of the HSM.
2. Now, add the HSM server to the client configuration by running the following command:
vtl addServer -n <HSM_ADDRESS> -c server.pem
Replace

3. Create the certificate and private key for the client by running the command:
vtl createcert -n <CLIENT_ADDRESS>
Replace
<CLIENT_ADDRESS> with the IP address or fully qualified host name of the client.
The name of the generated certificates includes the <CLIENT_ADDRESS> . The output of this command looks similar
to:
$ Private Key created and written to:

/usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>Key.pem
Certificate created and written to:
/usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>.pem
4. Copy the client certificate and private key to the HSM server by running the command:
scp /usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>.pem hsm_admin@<HSM_ADDRESS>:.
Replace
1. SSH into the HSM as the admin the HSM server and register the client by runningone of the following commands.
If the <CLIENT_ADDRESS> is the IP address of the client:
client register -client ${CLIENT_NAME} -ip <CLIENT_ADDRESS>
If the <CLIENT_ADDRESS> is the fully qualified host name of the client:
client register -client ${CLIENT_NAME} -hostname <CLIENT_ADDRESS>
Replace
{CLIENT_NAME} with the name of the client. This value can be anything meaningful to you.
<CLIENT_ADDRESS> with either the IP address or fully qualified host name of the client.
2. Because network address translation (NAT) exists between the client and the HSM, we need to disable client source IP
address validation by the Network Trust Link Server (NTLS) upon Network Trust Link Agent (NTLA) client connection.
Disable ip check on the HSM server and then restart the NTLS service on the HSM server by running the following
commands:
ntls ipcheck disable

service restart ntls
3. Assign a partition to the newly created client on the HSM server by running the following command:
client assignpartition -client ${CLIENT_NAME} -partition ${PARTITION_NAME}
Replace

{CLIENT_NAME} with the name that you gave to your HSM client.
{PARTITION_NAME} with the name of the HSM partition you created in Part one, step 1.
You can verify the command worked by running the following command:
$ client show -client ${CLIENT_NAME}
The output will look similar to:
$ ClientID: hsmclient
IPAddress: 10.220.203.73
HTL Required: no
OTT Expiry: n/a
Partitions: "partition1"
Command Result : 0 (Success)
4. Verify the client can connect to HSM server by running the command:
vtl verify
$ The following Luna SA Slots/Partitions were found:

Slot Serial # Label
==== ================ =====
0 500752010 partition1
5. Create a configs folder on the client and then copy the server.pem certificate from Part two, step 1 and the
<CLIENT_ADDRESS>Key.pem and <CLIENT_ADDRESS>.pem files from Part two, step 3 into the folder:
Copy server.pem to configs/server.pem

Copy /usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>Key.pem to configs/key.pem
Copy /usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>.pem to configs/cert.pem

To configure HSM on your blockchain network, build an HSM client image as follows below.
Build an HSM client image

Next we build a Docker file that contains the HSM client image. These instructions assume that you have successfully configured
your HSM appliance and HSM client. Use these steps to generate an image that is consumable by the IBM Blockchain Platform
operator.
Step one: Modify the HSM client configuration.

Step two: Build the HSM client image.
Step three: Push the Docker image to your container registry.
Step four: Create a Kubernetes secret hsmcrypto.
Step five: Create the HSM configmap.
Step one: Modify the HSM client configuration
Each HSM has its own configuration file that is typically named Chrystoki.conf . This is the main configuration file for the HSM
integration and controls many aspects of the HSM client operation. After you install the HSM client, you need to modify the
etc/Chrystoki.conf file to point to the hsm folder that contains the HSM shared object library and cryptographic material.

The paths specified in Chrystoki.conf represent the location where the IBM Blockchain Platform operator mounts these files
on the containers. You need to modify parameters inside the Chrystoki2 and LunaSA Client sections as follows:
Chrystoki2 settings
LibUnix: Name of the Chrystoki2 library on x86 Linux/UNIX operating systems. The actual name of the library depends on
the type of HSM you are using.
LibUNIX64: Name of the Chrystoki2 library on 64-bit Linux/UNIX operating systems. The actual name of the library
depends on the type of HSM you are using.
LunaSA Client settings Typically no changes would be required here unless you have explicitly modified the names of these
files.
ClientPrivKeyFile: Name of the HSM client private key.

ClientCertFile: Name of the HSM client certificate.
ServerCAFile: Name of the HSM server certificate.
The following example shows what the file would look like if you were using IBM Cloud HSM. It provides the path to the HSM
shared object, certificate and keys. Note that the naming of these files depends on the HSM library that is being used.
Chrystoki2 = {
LibUNIX = /hsm/libCryptoki2.so;
LibUNIX64 = /hsm/libCryptoki2_64.so;
}
...
LunaSA Client = {
...
ClientPrivKeyFile = /hsm/key.pem;
ClientCertFile = /hsm/cert.pem;
ServerCAFile = /hsm/cafile.pem;
...
}
Step two: Build the HSM client image
The HSM client image can be built with a Docker file similar to the following:
The following Docker file is for IBM Cloud HSM. If you are not using IBM Cloud HSM, you need to build your own Docker
file.
You should be aware that this Docker file automatically accepts the Gemalto client license.
Note that the 64 folder inside the Docker file is required for installing the HSM client.
FROM registry.access.redhat.com/ubi8/ubi-minimal as builder
## This directory contains the installation files for gemalto/luna client

COPY 64 64
RUN microdnf install -y \

gcc \
gcc-c++ \
openssh-clients \
bind-utils \
iputils \
&& cd 64 && \
# NOTE we are accepting the license for installing gemalto client here
# please take a look at the license before moving forward
echo "y" | ./install.sh -p sa
### Final image ###
FROM registry.access.redhat.com/ubi8/ubi-minimal
# Copy the library files from builder

COPY --from=builder /usr/lib/libCryptoki2_64.so /usr/lib/libCryptoki2_64.so
COPY --from=builder /usr/lib/libCryptoki2_64.so.2 /usr/lib/libCryptoki2_64.so.2
COPY --from=builder /usr/lib/libCryptoki2_64.so.6.3.0 /usr/lib/libCryptoki2_64.so.6.3.0
Now, run the following command to build the Docker image:
docker build -t hsm-client:v1 -f Dockerfile .
Step three: Push the Docker image to your container registry
After the image is built, the next step is to push the image to your Docker registry (for example, Docker Hub). The commands
look similar to:
docker login -u <DOCKER_HUB_ID> -p <DOCKER_HUB_PWD>

docker tag hsm-client:v1 <DOCKER_HUB_ID>/hsm-client:v1
docker push <DOCKER_HUB_ID>/hsm-client:v1
Replace <DOCKER_HUB_ID> with your Docker Hub id.

Replace <DOCKER_HUB_PWD> with your Docker Hub password.
Create a Kubernetes image pull secret
If the HSM client image that you published is not public, then the operator requires an image pull secret that contains a
valid username and password (or access token) for the container registry. If the image is public, the imagepullsecret is not
required and you can skip this command. To build the image pull secret named hsm-docker-secret , run the following
command in the namespace or project where you deployed the service:
kubectl create secret docker-registry hsm-docker-secret --docker-server=<DOCKER_REGISTRY_SERVER> --

docker-username=<DOCKER_USER> --docker-password=<DOCKER_PASSWORD> --docker-email=<DOCKER_EMAIL> -n
<NAMESPACE>
Replace:
DOCKER_REGISTRY_SERVER - Registry server url where the HSM client image is hosted.
DOCKER_USER - Valid username with access to HSM client image in the container registry.
DOCKER_PASSWORD - Valid password or access token for the HSM client image in the container registry.
DOCKER_EMAIL - Email address for container registry user.
NAMESPACE - Name of the project or namespace that is visible on the consoleSupport page.
These instructions are obviously for the Docker registry. If you are using the IBM Container Registry, then you need to set up your
own image pull secret in your cluster:
$ - [Using an image pull secret to access images in other IBM Cloud accounts or external private
registries from non-default Kubernetes namespaces](/docs/containers?topic=containers-registry#other)
- [Copying an existing image pull secret](/docs/containers?topic=containers-
registry#copy_imagePullSecret)
- [Referring to the image pull secret in your pod deployment](/docs/containers?topic=containers-
images#pod_imagePullSecret)
Step four: Create a Kubernetes secret hsmcrypto

In order for a CA, peer, or ordering node to be able to communicate with the HSM client image you need to create a Kubernetes
secret named hsmcrypto that contains the keys and configuration files for the HSM that you are using. When the console
deploys a node that is configured with HSM, it uses this secret to access the HSM client image keys and configuration files.
The Kubernetes secret needs to be created in the IBM Blockchain Platform service instance namespace that is visible on the
console Support page. If you are using the IBM Cloud HSM, the command would be:

$ kubectl create secret generic hsmcrypto -n <NAMESPACE> --from-file=Chrystoki.conf --from-
file=cert.pem --from-file=key.pem --from-file=server.pem
Replace <NAMESPACE> with the name of your service instance namespace or OpenShift project If you are not using IBM Cloud
HSM, you need to replace the values of the --from-file parameters with the set of certificates and configuration files that are
required for your HSM client image.
When successful, the output looks similar to:
$ secret/hsmcrypto created
To verify the contents of the secret, run the command:
kubectl get secret -n <namespace> hsmcrypto -o yaml
You should see results similar to:
$ apiVersion: v1
data:
Chrystoki.conf: ""
cafile.pem: ""
cert.pem: ""
key.pem: ""
kind: Secret
metadata:
name: hsmcrypto
namespace: <NAMESPACE>
Step five: Create the HSM configmap

Because the console needs to know the configuration settings to use for your HSM, you need to create a Kubernetes configmap
to store these values. The configMap settings depend on whether you configured a daemon for your HSM or not. In that case, the
IBM Blockchain Platform operator uses the HSM configuration passed in this configmap to get the details about the HSM client
image, such as what image pull secret to use, and the folder mounts that are required. Based on the information provided, when
a CA, peer, or ordering node is deployed with HSM enabled, the operator mounts required the files for the HSM client image. If
you are using a daemon with your HSM, skip ahead to Configure the operator to work with an HSM daemon.
Configure the operator to work with an HSM that does not use a daemon
Copy the following text and save it to a file named ibp-hsm-config.yaml :
version: v1
type: hsm
resources:
limits: {}
requests: {}
securityContext:
privileged: false
runAsNonRoot: false
runAsUser: 0
library:
image: <HSM_IMAGE_URL>
auth:
imagePullSecret: <IMAGE_PULL_SECRET>
filepath: <HSM_LIBRARY_FILE_PATH>
envs:
- name: <ENVIRONMENT_VARIABLE_NAME>
value: <ENVIRONMENT_VARIABLE_VALUE>
mountpaths:
- mountpath: <MOUNTPATH>
name: <MOUNTPATH_NAME>

secret: <HSM_CRYPTO_SECRET>
paths:
- key: <KEY>
path: <PATH>
- key: <KEY>
path: <PATH>
paths:
- key: <KEY>
path: <PATH>
- key: <KEY>
path: <PATH>
HSM_IMAGE_URL: URL of the HSM client image that you published to your container registry.
IMAGE_PULL_SECRET: (Optional) Name of the image pull secret hsm-docker-secret that you created in the same
namespace as your service. Only required if the HSM client image is not publicly available. Important: If an image pull
secret is not required, set this value to "".
ENVIRONMENT_VARIABLE_NAME - If there are any environment variables that need to be set for the HSM client, specify
them individually.
ENVIRONMENT_VARIABLE_VALUE - Value that corresponds to the ENVIRONMENT_VARIABLE_NAME.
HSM_LIBRARY_FILE_PATH: Path to the HSM library file, for example, /usr/lib/libCryptoki2_64.so.
MOUNTPATH: Location where the file or folder should be mounted.
MOUNTPATH_NAME: Name you want to use for the mountpath.
KEY: Name of the key inside the hsmcrypto Kubernetes secret.
PATH: Mount location of the file path where the key should be mounted.
HSM_CRYPTO_SECRET: Name of the Kubernetes secret that contains the keys and configuration files for the HSM that is
used by the mountpath.
Each HSM likely has a different set of keys that are required by the HSM client. Optionally replicate the "key " and " path "
sections according to the number required by your HSM client. Similarly, if multiple sets of folders need to be mounted, you can
replicate the " mountpath " section.
For example, if you are using IBM Cloud HSM, the file looks similar to:
version: v1
type: hsm
library:
image: us.icr.io/hsm/gemalto-client:v1.2.3-amd64
auth:
imagePullSecret: hsm-docker-secret
filepath: /usr/lib/libCryptoki2_64.so
mountpaths:
- mountpath: /hsm
name: hsmcrypto
paths:
- key: cafile.pem
path: cafile.pem
- key: cert.pem
path: cert.pem
- key: key.pem
path: key.pem
- key: server.pem
path: server.pem
secret: hsmcrypto
- mountpath: /etc/Chrystoki.conf
name: hsmconfig
secret: hsmcrypto
subpath: Chrystoki.conf

In this example, the first mountpath contains four configuration files (cafile.pem, cert.pem, key.pem, server.pem) and the
hsmcrypto secret, and all of them are mounted to the mountpath /hsm . The actual name of the mountpath is hsmcrypto , and
it contains an exact mapping of the key value pair to the Kubernetes secret and the location to mount it to. For example,
cafile.pem is read from the path cafile.pem in the hsmcrypto mountpath using the hsmcrypto secret and mounted to
/hsm/cafile.pem .
A second mountpath is included for the HSM /etc/Chrystoki.conf file. Because the HSM requires its config file in the /etc
folder, which is a system directory, we need to use the subpath parameter to avoid replacing the entire /etc directory. If the
subpath is not used, the entire /etc directory is replaced with the volume being mounted.
You have completed the HSM configuration for your blockchain network. Now when you deploy a new CA, peer, or ordering node,
you can configure it to use the HSM that you have configured here. See Configuring a CA, peer, or ordering node to use the HSM
for details.
Configure the operator to work with an HSM daemon
If you configured an HSM daemon, the following sample configuration shows how to configure the openCryptoki zHSM on the
operator. You need to customize the settings according to your daemon.
daemon:
image: us.icr.io/ibp-test/opencryptoki-deamon:s390x-1.0.1
auth:
imagePullSecret: "ibprepo-key-secret"
resources:
limits:
cex.s390.ibm.com/ibp: 1
securityContext:
privileged: false
runAsNonRoot: false
runAsUser: 0
library:
filepath: /hsm/opencryptoki/libopencryptoki.so.0.0.0
auth:
envs:
- name: LD_LIBRARY_PATH
value: /stdll
mountpaths:
- mountpath: /usr/sbin/pkcsslotd
name: pkcsslotd
volumeSource:
emptyDir:
medium: Memory
- mountpath: /var/run
name: varrun
volumeSource:
emptyDir:
medium: Memory
- mountpath: /var/lib/opencryptoki
name: tokeninfo
usePVC: true
- mountpath: /etc/opencryptoki
name: opencryptoki-config
volumeSource:
emptyDir:
medium: Memory
- mountpath: /var/lock/opencryptoki
name: lock
volumeSource:
emptyDir:

medium: Memory
- mountpath: /stdll
name: stdll
volumeSource:
emptyDir:
medium: Memory
type: hsm
version: v1
In the daemon: section, provide the URL of the HSM daemon image that you created. If the image is not hosted publicly,
then you need to create the appropriate pull secret and specify it here as well.
In the library: section, provide the URL of the HSM client image that you created in step two. This is the client that the
CA, peer, and ordering node will use to talk to the HSM daemon. The filepath: is the location of the shared object
library in the image. If the image is not hosted publicly then the user must create the appropriate pull secret and specify it
as well.
In the envs: section, provide the list of environment variables that are required to configure the HSM.
In the mountpaths: section, provide all the necessary artifacts such as config, shared object libraries, shared memory,
etc. that are needed to communicate with the HSM daemon. These settings are vendor-specific as it is your responsibility
to know what directories or files need to be mounted. When the CA, peer, and ordering nodes are deployed, these
mountpaths will be mounted on to their containers along with the HSM client. Most of these mountpaths can be of type
Memory , however, if there are files that need to persist, then set usePVC: true . When set, the operator stores the files in
the mountpath in a persistent medium, by leveraging the PVCs of the CA, peer, and ordering node as the persistent
medium.
Run the following command to create the configmap named ibp-hsm-config in your cluster namespace or project:
kubectl create configmap ibp-hsm-config --from-file=ibp-hsm-config.yaml -n <NAMESPACE>
The output looks similar to:
$ configmap/ibp-hsm-config created
What's next
After you have used these instructions to configure your IBM Cloud HSM and build theHSM client image, you are ready to
configure your blockchain nodes to use the HSM. When you create a CA, peer, or ordering node, select the HSM Advanced
deployment option to configure the node to use this HSM.
Important: When a node is configured with HSM, a temporary Kubernetes job is started to run this HSM "enrollment"
process. Before configuring a node to use HSM, ensure that you have enough resources in your cluster to support this job
that takes approximately 0.1CPU and 100M memory.
On the HSM configuration panel, the Use HSM client image toggle is visible. When it is on, you can enter the following values:
HSM label - Enter the name of the HSM partition to be used for this node.
HSM PIN - Enter the PIN for the HSM slot.
When the node is deployed, a private key for the specified node enroll ID and secret is generated by the HSM and stored
securely in the appliance.

Ansible Playbooks
Getting started with Ansible playbooks on the IBM Blockchain Platform
Customers who are interested in automating their IBM® Blockchain Platform network deployments can use Ansible playbooks to
build out their networks.
Target audience: This topic is designed for network creators and system administrators who are responsible for planning and
configuring IBM Blockchain networks on IBM Cloud or on their own Kubernetes cluster and are new to Ansible playbooks.
What is Ansible
Ansible is a powerful open source automation language and in the context of the IBM Blockchain Platform can be used to script
deployments. It is a configuration management tool that automates the network deployment across multiple hosts by the use of
Ansible playbooks. Playbooks declare configurations and orchestrate the steps of any manual ordered process, synchronously
or asynchronously.
Each playbook is composed of one or more plays in a list. The goal of a playbook is to map a group of hosts to some well-defined
roles, represented by actions that Ansible calls tasks. Basically, a task is simply a call to an Ansible module.
Ansible Content Collections, or simply collections, are the mechanism for distributing, maintaining, and consuming the
automation. Combining multiple types of Ansible content (playbooks, roles, modules, and plug-ins) into a collection, adds
flexibility and scalability for automating your blockchain network deployment. The open source collections are published in
Ansible Galaxy where they can be freely downloaded. Check out their documentation for more education.
IBM Blockchain Platform offers an Ansible collection that includes the pertinent roles, modules, and documentation for rapidly
deploying, replicating, and tearing down blockchain networks in a reproducible fashion.
The Ansible collection includes a set of playbooks that automate the tasks that you would otherwise perform from the console
UI or by using the APIs, for example deploy a Certificate Authority (CA). But the playbooks are more robust than just that. The
playbooks automate a logical series of tasks that you would repeatedly perform in the console, for example create a CA, register
identities, create an organization MSP definition, and create a peer. And all of these steps can be performed by running a single
playbook.
Tip: This tutorial series is designed for users who are unfamiliar with how to use Ansible playbooks. Experienced Ansible
users can go directly to the collection documentation to get started.
How does the IBM Blockchain Platform Ansible collection work?

The IBM Blockchain Platform Ansible collection uses the IBM Blockchain Platform REST APIs. It includes an entire set of
playbooks that can be used to deploy your peer, Certificate Authority (CA), and ordering service nodes, create organizations,
identities, channels, and deploy smart contracts. And when you need to start over, there are scripts for tearing it all back down.
These playbooks will run on your blockchain network that is running on IBM Cloud or on your own Kubernetes cluster where the
IBM Blockchain Platform is installed.
Why would I want to use an Ansible playbook?

The Ansible playbooks include a set of modules that you can use to automate the deployment of your nodes, registering of
identities, channel creation, and smart contracts installation and instantiation.
Deploying your blockchain network After you deploy the IBM Blockchain Platform to a Kubernetes cluster on IBM Cloud,

or on your supported Kubernetes distribution, there are three ways to build your network. To understand the benefit of
using the Ansible playbooks, we compare the options:
1. Deploy your nodes and configure your network manually using the console user interface.This option is most
useful for getting started and learning about the platform and how the console works. It requires stepping through
multiple panels to configure all the settings for your nodes, organizations, channels, and smart contracts.
2. Use the IBM Blockchain Platform REST APIs to build your network. This option is for advanced users who want to
leverage the available REST APIs, often in conjunction with the Hyperledger Fabric APIs, to set up and administer
their blockchain network. Configuration is done through editing API parameters. Because the IBM Blockchain
Platform APIs are mainly for create, retrieve, update, and delete operations on a node, you may need to also learn
and use the Hyperledger Fabric APIs for some tasks.
3. Use the IBM Blockchain Platform Ansible Collection. After you are familiar with the process to set up the various
nodes, organizations, channels, and smart contracts, you might want to automate the process. The Ansible
playbooks provide a simple, straightforward, way to build and deploy a reproducible network. For getting started, a
set of scripts is provided that stitches the relevant playbooks together into a single executable shell script of
deployments to perform on your network. Configuration is done through editing .yml files. The Ansible playbooks
also automate some of the tasks performed by the Fabric APIs, such as creating a channel, joining a peer to a
channel, and installing and instantiating smart contracts. Even more, there are playbooks available for tearing down
the configuration so you can reset your network as needed. This option is a great option for setting up networks for
POCs, demos, development, and test networks.
The Ansible playbooks provide an easy-to-use, automated process to replicate your blockchain networks on-demand.
All components that are deployed with the playbooks are also visible in the console where you can interact with
them as normal and govern your network.
Considerations and Limitations

Console wallet identities - When you use the Ansible playbooks to deploy blockchain nodes, the identities that are required to
operate the nodes in the network are generated for you. Don't worry, you have the opportunity to configure the node enroll ID
and secrets. But the identities aren't added to the console wallet in the browser. That is a simple manual import step that you
need to perform after the playbooks finish and is described in the tutorial on using the playbooks to build your network.
Getting started
There are multiple ways to install the Ansible collection. One option is to install all of the prerequisite software locally, which can
be cumbersome for first-time Ansible users. Another simpler option is to run the playbooks from a Docker image. Because using
a Docker image completely bypasses the need for the prerequisite setup (the prereqs are part of the Docker image), this
approach is by far the simplest option and is the process that we use throughout these tutorials. This option does require that
you install Docker before proceeding. To determine whether Docker is installed, run the command docker --version . If it is
installed, you'll see something similar to:
$ ```
Docker version 18.09.2, build 6247962
```
If you do not have Docker installed, see install Docker to download and install it. You can also check out the Docker site for
more education and documentation.
Advanced users can review the Ansible collection documentation for other installation options.

Next steps
After the image is successfully built, it can be used to run a playbook. To get started with the playbooks see Building an IBM
Blockchain Platform network using Ansible playbooks if you already have an existing instance of the IBM Blockchain Platform
deployed and want to use the Ansible playbooks to deploy your network components.
Where to find support

Ansible is an open source technology, therefore the Ansible playbooks are not officially supported by IBM. For support related to
the usage of the IBM Blockchain Platform and Ansible playbooks open an issue in the GitHub repository
Building an IBM Blockchain Platform network using Ansible playbooks

Customers can use Ansible playbooks to automate the setup and tear down of IBM® Blockchain Platform network components.
Target audience: This topic is designed for system administrators or operators who are responsible for creating or removing
components in an IBM Blockchain Platform network and are new to Ansible playbooks.
In this tutorial, we gather the connection information to your console and demonstrate how to use that information to configure
the playbooks. The playbooks group and automate common network deployment tasks so that you can bypass manually
configuring your network from the console. We teach you how to run an individual playbook and then how to run them
sequentially from a script. In just a few minutes, you can deploy an entire set of blockchain components that are ready to
process transactions on your IBM Blockchain Platform network.
The Ansible scripts can be used to build the following network that includes two organizations (Org1 and Org2) that each
contains one peer and an ordering service with a channel joined by both peers. It's a simple process to customize the playbooks
with your own component or organization names. They can also be used to deploy smart contracts on the channel. And as you
become more proficient, you can use the playbooks to build additional organizations, peers, ordering services, and channels
according to your use case.
Figure 1. Network components created by the Ansible playbooks
Prerequisites
Before using the playbook, you need to complete the following steps:
Link an instance of the IBM Blockchain Platform to your Kubernetes cluster on IBM Cloud.
Review the topic on Getting started with Ansible playbooks on the IBM Blockchain Platform.
Install Docker.
Step one: Gather console connection information

After you deploy an IBM Blockchain Platform service instance, you need to gather the connection information for the console.
When your cluster is running in IBM Cloud, you need to create service credentials for the IBM Blockchain Platform service
instance. The Ansible playbooks use the IBM Blockchain Platform REST APIs to interact with the console. The REST APIs use the
API key (api_key) and API endpoint (api_endpoint) to authenticate with the server and retrieve a Cloud Identity and Access
Management (IAM) access token. The values of the api_endpoint and api_key for the console can be found in the generated
service credentials.
Follow instructions on retrieving service credentials in IBM Cloud to gather these values now that are used with the playbooks
later in this topic.

Step two: Clone the Ansible collection
The Ansible collection source code is available in a GitHub repository. You need to clone the Ansible collection to your local
system so that you can run the playbooks and customize them according to your use case. From the command line on your local
system run the command:
$ ```
git clone https://github.com/IBM-Blockchain/ansible-collection.git
```
We'll explore the contents of this collection in the next section.
Step three: Get started with using the playbooks

After you clone the Ansible collection to your local system, open the ansible-collection directory and navigate to the
tutorial folder and take a moment to review the contents.
$ ```bash
cd ansible-collection/tutorial
```
The first thing that you notice is that the playbook .yml files are numbered. Because the playbooks build on each other, the
numbers help you understand the order that they should be run. When you want to change some of the configuration properties,
you can edit the .yml files and insert your own custom values, for example, if you want to customize a node name or use a
different enrollment ID. Each playbook includes either a role or a task. A role includes a set of tasks that in turn call the
associated modules that submit the requests to your cluster.
The next thing to notice is the set of variable files ordering-org-vars.yml (Ordering Org), org1-vars.yml (Org1), and
org2-vars.yml (Org2) that define the IBM Blockchain Platform console connection details for each organization. These
variable files are used by the playbook when you run it. This means that before you run a playbook, if it uses a variable file, you
need to customize the associated variable file with the connection information that you gathered in the previous step. When a
playbook requires a variables file, it is included in the playbook .yml file.
The variable files include the following four fields that define your connection information to your console:
$ ```
api_endpoint: https://ibp-console.example.org:32000
api_authtype: ibmcloud
api_key: xxxxxxxx
api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
You need to replace the fields with the following values:
api_endpoint - Set this value to the api_endpoint from your service credentials.
api_authtype - Because your cluster is in IBM Cloud, this value needs to be set toibmcloud.
api_key - to the value of api_key contained in the service credentials.
api_secret - This value is not used for clusters in IBM Cloud. No value is required here.
Refer to Gather console connection information for instructions on how to get the service credentials.
You can go ahead now and modify the ordering-org-vars.yml (Ordering Org), org1-vars.yml (Org1), and org2-vars.yml
files with your console connection information.
There is also a common variables file, common-vars.yml . You do not need to edit this variable file right now. This file contains
variables that are used by multiple organizations, for example the name of the channel that will be created, and the name of the

smart contract that will be deployed. Later, when you are ready to create your own custom network you will want to modify these
values according to your business use case.
Step four: Run a playbook
Note: These instructions assume that you have installed Docker) in order to use the Ansible playbooks. If you have
installed all of the prerequisites locally on your system instead, you can refer to the Ansible documentation for
instructions on how to run the playbooks.
1. We use a Docker command to run the first playbook that creates an ordering organization that is namedOrdering Org,
with a certificate authority named Ordering Org CA, and finally a single node ordering service named Ordering Service. If
you have not already, go ahead and modify the console connection variables inside the ordering-org-vars.yml by
using the instructions from the previous section. You are now ready to run an Ansible playbook from Docker.
The following command invokes the 01-create-ordering-organization-components.yml playbook.
docker run --rm -v <FULLY-QUALIFIED-PATH-TO-PLAYBOOKS>:/playbooks ibmcom/ibp-ansible ansible-

playbook /playbooks/<PLAYBOOK>.yml
where:
--rm tells Docker to remove the container when the command completes.
-v <FULLY-QUALIFIED-PATH-TO-PLAYBOOKS> is used to mount the tutorial folder into the Docker container.
Replace <FULLY-QUALIFIED-PATH-TO-PLAYBOOKS> with the fully qualified path to where the tutorial folder
resides on your local system. When you run the command from the tutorial folder you can replace this value with
$PWD.
ibmcom/ibp-ansible represents the tag of the Docker image that is published by IBM.
<PLAYBOOK> is used to designate which playbook to run.
For example:
$ cd tutorial
docker run --rm -v $PWD:/playbooks ibmcom/ibp-ansible ansible-playbook /playbooks/01-
create-ordering-organization-components.yml
While the command is running, you see output from each task. You can safely ignore the following warning:
$ [WARNING]: provided hosts list is empty, only localhost is available. Note that the
implicit localhost does not match 'all'`.
When the playbook is finished, in the PLAY RECAP section, you see output similar to:
$ PLAY RECAP *********************************************************************

localhost : ok=7 changed=5 unreachable=0 failed=0 skipped=1
rescued=0 ignored=0
If the playbook completes successfully, you should see failed=0 . Go ahead now and log in to your console to
confirm that Ordering Org CA, Ordering Org organization, and Ordering Service was created.
2. The same instructions can be repeated for the next playbook, 02-create-endorsing-organization-components.yml .
This playbook creates an endorsing organization named Org1, with a certificate authority named Org1 CA, and then a peer
named Org1 Peer. When you open the playbook, notice in the comments that this playbook uses a different variables file
org1-vars.yml . Edit that file with your console connection information. And then run that playbook:

docker run --rm -v $PWD:/playbooks ibmcom/ibp-ansible ansible-playbook /playbooks/02-create-
endorsing-organization-components.yml"
Again, if you check your console, you can see that the Org1 CA, Org1 organization, and Org1 Peer was created.
3. You can continue running each playbook individually in the list to stand up a basic network that contains an ordering
service, two peer organizations, two peers, and a channel. The playbooks also install smart contracts on the peers and
instantiate them on the channel.
Check out this topic on Exploring the playbooks for more information about how each playbook works.
By now, you are probably interested in scripting these commands together to stand up or even tear down the components. The
next section walks you through how to do that.
Step five: Run a script

At this point you've experienced how powerful the Ansible playbooks can be for programmatically deploying network
components, creating channels and installing and instantiating smart contracts. But it is likely that you will want to script them
together to build reproducible networks. That's why in the tutorial folder a set of scripts are provided that run groups of
playbooks together in a logical order:
build_network.sh - This is a script that runs a set of playbooks that create an entire simple network, the same one that
can be created if you manually build the network by completing the Build a network tutorial. When you call the script with
the build option, it configures a single node ordering service, a peer organization and a peer. It installs theFabCar
smart contract on the peer, creates a channel and joins the peer to the channel. If you run the script with the destroy
option it removes all of these artifacts from your cluster. For details, see Building a network.
join_network.sh - Run this script when you want to join a peer organization to an existing channel. For more details see
Joining a network.
deploy_smart_contract.sh - This script can be used to install a smart contract on one or more peers in your
organization and instantiate it on a channel. For more details, see Deploying the smart contract.
Before running any script, you need to update the console connection settings in the ordering-org-var.yml , org1-
vars.yml , and org2-vars.yml files. Go ahead and try out the build_network.sh script by running the following Docker
command from your tutorial folder:
docker run --rm -v "$PWD:/tutorials" ibmcom/ibp-ansible /tutorials/build_network.sh -i build
Notice that the playbooks will run even if the artifacts that you are deploying already exist. In that case, you can see in thePLAY
RECAP status that changed=0 , meaning the playbook detected that the node exists and did not try to re-create it. You can also
run the build_network.sh with the destroy option to remove all the nodes and metadata that were created when you ran
the build_network.sh script with the build option. Give it a try now by running the command:
docker run --rm -v "$PWD:/tutorials" ibmcom/ibp-ansible /tutorials/build_network.sh -i destroy
Hints and Tips

Tip Action

Increasing Some clusters perform faster than others. The scripts use a default wait timeout of600 seconds, which is
the wait sufficient for most environments. The wait timeout represents the maximum amount of time the playbook
timeout waits for the underlying transactions to complete before it logs a failure. If you need to increase the
timeout, open the associated variables file (ordering-org-vars.yml, org1-vars.yml, or org2-
vars.yml) and modify the value of the wait_timeout: parameter.
Customizing The playbooks use the organization names that are defined in the common-vars.yml file. When you are
organization ready to configure your own organizations, you can edit the file and specify the preferred organization
names names for your network.
Customizing The default ordering service name is defined in the common-vars.yml file in the ordering_service_name
the name of parameter. Edit this value to specify the preferred name of the ordering service.
the ordering
service
Adjusting By default, the 01-create-ordering-organization-components.yml playbook is configured to create a

how many single node ordering service. If your cluster has the resources to support additional ordering nodes in the
ordering ordering service, you can modify how many ordering nodes are created when the ordering service is
nodes are deployed by editing the 01-create-ordering-organization-components.yml playbook and specifying
created for the number of ordering nodes that you want to deploy in the ordering_service_nodes: parameter.
an ordering
service
Adjusting You can customize the resources that are allocated to a node by editing theresources block of its
node associated module. For example, to modify the CPU and memory that is allocated to a CA node, navigate
resources to your clone of the certificate_authority module on your local system. Scroll down to theresources
section and modify the values that are assigned to cpu and memory. Likewise, you can modify peer
resources in your clone of the peer module or the ordering service resources in the ordering service
module.
Using your By default, the 19-install-chaincode.yml and 20-instantiate-chaincode.yml playbooks use the
own smart Fabric 2.0 smart contract lifecycle with the FabCar sample smart contract. When you are ready to deploy
contract your own smart contract, you need to:
1. Include the smart contract package in the tutorial directory and name it using the format
<SMART-CONTRACT-NAME>@<VERSION>.tar.gz.
2. Refer to your smart contract by replacing the value of the smart_contract_base_name: and
smart_contract_version: parameters in the common-vars.yml file.
Using your When the playbooks deploy a node, it uses the enroll IDs specified in the 01-create-ordering-
own enroll organization-components.yml and 02-create-endorsing-organization-components.yml files. The
ID and associated enroll secrets are provided in the corresponding variable files ordering-org-vars.yml, org1-
secrets vars.yml, and org2-vars.yml. You can customize the values of the enroll ID and secrets in these files
according to your needs.
Table 1. Hints and tips for using the Ansible collection
Next steps
Now that you have used the playbooks to deploy your components or even scripted the deployment of your network, you can
continue to use the console UI to interact with and govern your blockchain components. You will notice right away that the
Ansible scripts do not associate an identity with the nodes that it deploys. If you plan to operate the nodes from the console, you
need to use a manual process to upload the node identities to the console wallet and associate them with the nodes. The
generated node identities are JSON files and are stored in the tutorial folder.
Generated identities
The following table lists the names of the JSON files that contain the identities that are generated by the build_network.sh
script with the build option or the join_network.sh script for the case of Org 2. If you customized organization names inside
the playbook .yml files, it is possible that your JSON files will be named differently. In order to operate the nodes from the
console, you need to import all of the generated identities into the console wallet by using the following process:

1. Navigate to the console wallet and click Add identity.
2. Click the Upload JSON tab and browse to the generated identities in the tutorial folder and click Add identity.
3. Repeat these steps for each identity file in the following table.
Ordering Org Org1 Org2
Organization Admin Ordering Org Admin.json Org1 Admin.json Org1 Admin.json
Organization CA Admin Ordering Org CA Admin.json Org1 CA Admin.json Org2 CA Admin.json
Table 1. File names of organization admin identities
Important: When you run the build_network.sh script with the destroy option, all of the nodes and associated
metadata are removed from your cluster, but any identities that you manually imported into the console wallet are not
removed. Before you run the build_network.sh script again with the build option, you need to manually remove each
identity, by opening it in the wallet and then clicking Remove identity.
Using the wallet identities from the preceding table, you can now follow the steps in the following table to associate identities for
each node type.
Associate an identity with CAs
Navigate to the Nodes tab.

Open the Ordering Org CA and click Associate identity.
Click the Existing CA tab and select the Ordering Org CA Admin.
If you created the endorsing organizations for the peers, repeat these steps for theOrg1 CA and Org2 CA nodes,
associating the Org1 CA Admin and Org2 CA Admin identities respectively.
Table 2. CA identities
Associate an identity with peers

Open the Org1 Peer and click Associate identity.
Select the Org1 Admin from the drop-down list and click Associate identity.
If you created the second endorsing organization (Org2) for the peers, repeat these steps for theOrg2 Peer by
associating the Org2 Admin identity.
Table 2. Peer identities
Associate an identity with the ordering service

Open the Ordering Service and click Associate identity.
Select the Ordering Org Admin from the drop-down list and click Associate identity.
Table 2. Ordering service identities
Summary
Congratulations. You have used the Ansible playbooks to configure IBM Blockchain Platform components on your cluster. You
know how to run a playbook individually and have some sample shell scripts that show how to run the playbooks together to

build a reproducible network and tear it back down. You can explore further by building your own playbooks that call the Ansible
modules or build your own custom scripts according to your network use case.

IBM Blockchain Platform console
Migrating to IBM Support for Hyperledger Fabric
Customers who are currently operating and using IBM® Blockchain Platform networks, either on-prem (software) or on IBM
Cloud (SaaS), are being advised of the eventual migration of both environments to the existing IBM Support for Hyperledger
Fabric on-prem (software) offering, which is a close relative of both IBM Blockchain Platform offerings.
Target audience: This topic is designed for network and system administrators who are responsible for planning, configuring and
migrating IBM Blockchain networks.
What is happening?
In September, 2021, IBM released the IBM Support for Hyperledger Fabric edition, which provides certified images of
Hyperledger Fabric open source code, accelerators, and IBM support for Fabric-based blockchain solutions. Given the functional
overlap with the IBM Blockchain Platform Software and SaaS editions, IBM will be withdrawing the IBM Blockchain Platform
SaaS edition in July, 2023.
Why is it happening?
To maintain a focused development, delivery & support effort for IBM Blockchain Platform, it has been determined that the IBM
Support for Hyperledger Fabric Support best recognizes the opensource foundation of the core code and aligns IBM’s value with
the support, certification, and accelerators.
How to transition licensing?

IBM Blockchain Platform SaaS PayGo customers can transition their license to IBM Support for Hyperledger Fabric during any
month, without any existing long-term customer commitment, through coordination with their IBM Blockchain Support team or
IBM Account Representative.
IBM Blockchain Platform SaaS subscription customers will be able to transition their license to IBM Support for Hyperledger
Fabric at the end of their current subscription commitment, or before July, 2023 (whichever comes first), with assistance from
their IBM Blockchain Support team or IBM Account Representative.
Planning and Considerations

IBM Support for Hyperledger Fabric supports the Hyperledger Fabric v2.x codebase (the v1.4 codebase goes out of support in
April, 2023) so existing environments need to utilize v2.x component images.
Documentation for the IBM Support for Hyperledger Fabric is a current IBM product offering; the documentation is available at
https://www.ibm.com/docs/en/hlf-support/1.0.0.
Next steps
Coming soon: Watch this space for details on how to migrate your IBM Blockchain Platform network to IBM Support for
Hyperledger Fabric.
Administering your console

There are various actions that you can take to manage your console behavior. This topic describes actions outside of the
blockchain node operations that aid you in your day-to-day usage of the console.

blockchain network.
Refreshing your console

If you are having trouble connecting to your console after you click Launch the IBM Blockchain Platform on the Welcome
back panel, or recently upgraded your OpenShift Container platform 3.11 to 4.x, the Refresh cluster button is a useful
mechanism to renew the connection between your console and your Kubernetes cluster on IBM Cloud. It can also be used to
upgrade to a newer release of the console, if one is available.
To access this button:
1. Log in to IBM Cloud and open IBM Cloud Resource list. Ensure that you log in with your IBM ID.
2. Your IBM Blockchain Platform service instance is visible under the Services twistie. Locate and click the IBM Blockchain
Platform service instance that you deployed.
3. On the Welcome Back panel, click Refresh cluster. The operation could take a few minutes while it re-establishes
connectivity to your Kubernetes cluster and refreshes the management console.
4. Click Launch IBM Blockchain Platform again.
Your console opens in your browser.
Adding and removing users from the console

Every user that accesses the console must be assigned an access policy with an IBM Cloud® Identity and Access Management
(IAM) user role defined. The policy determines what actions the user can perform within the console. The IBM® Blockchain
Platform console is provisioned with the email address of the IBM Cloud owner as the console administrator. By default, this
IBM Cloud user is given the Manager role for the IBM Blockchain Platform service in IAM. The console administrator can then
grant other users access to the console by using the IAM UI. For more information about IAM see What is IAM.
For instructions on how to add new user see Inviting users to an account with the following additional details:
Under Assign users additional access, click IAM services.

Under What type of access to you want to assign?, type Blockchain Platform.
Under Service Instance Name, select the service instance where you want to add the user.
Under Service access you can click each pill to see the specific actions associated to each role, similar to the table in the
next section.
Role to permissions mapping table

Role Permissions
Manager As a Manager, you have permissions beyond the Writer role. You can do everything a Reader and Writer can do
as well as:
Provision new components such as CAs, peers, and ordering services, by using the console or APIs.
Override configuration settings on components.
Delete provisioned components by using the console or APIs.
Change console logging levels by using the console or APIs.
Restart the console by using an API.
Link a blockchain service instance to a Kubernetes cluster.

Writer As a Writer, you have permissions beyond the Reader role, including:
Import components by using the console or APIs.
Remove imported components by using the console or APIs.
Register users on a CA.
Add or remove notifications by using the console or APIs.
Refresh your connected cluster from the service instance.
Reader As a reader, you can perform read-only actions including:

View console UI.
View console log.
Export components.
Issue any GET API.
View the blockchain console UI.
Table 1. Role to permissions mapping table
Permissions are cumulative. If you select a Manager role, the user will also be able to perform all Writer and Reader actions, you
are not required to additionally check those roles. Likewise, a user with the Writer role will be able to perform all of the actions
in the Reader role. For console access, you need to only select a role under theService Access Roles, you do not need to select
anything under the Platform Access Roles. Check the corresponding role under Assign platform access role when it is
important that the service instance is visible in the invited user's IBM Cloud dashboard.
Important: After you add new users to the console, the users might not be able to view all the nodes, channels, or smart
contracts other users have deployed. To work with these components, each user needs to import the associated identities
into their own console wallet. For more information, see Storing identities in your console wallet.
If you need to modify a user's role:
1. From the menu bar, click Manage > Access (IAM) and then select Users.
2. Click the Actions menu next to the user you want to modify and selectAssign access.
3. Select the tile Assign access to resources.
4. From the Services drop-down list, select Blockchain Platform 2.0.
5. Scroll down to Select roles.
6. Under Assign service access roles, choose a role for the user, which can be Manager, Writer, and Reader.
7. Click Assign.
When you need to remove a user's access to the console, follow instructions in the IAM Removing users topic.
Assigning access roles to individual or groups of users in IAM

When you set IBM Cloud IAM policies, you can assign roles to an individual user or to a group of users.
Individual users
You might have a specific user that needs more or less permissions than the rest of your team. You can customize
permissions on an individual basis so that each person has the permissions that they need to complete their tasks. You can
assign more than one IBM Cloud IAM role to each user.
Multiple users in an access group
You can create a group of users and then assign permissions to that group. For example, you can group all team leaders and
assign administrator access to the group. Then, you can group all developers and assign only write access to that group. You
can assign more than one IBM Cloud IAM role to each access group. When you assign permissions to a group, any user that

is added or removed from that group is affected. If you add a user to the group, then they also have the additional access. If
they are removed, their access is revoked.
Note: The users that you add in IAM are simply email addresses of users who can log in to the console. They have no
relationship to the Available Organizations in the Organizations tab or the identities stored by the console wallet.
Updating the administrator email address

If the console is used by multiple people or organizations, it is recommended that you create a functional email address to
access your network. The use of a functional email allows you to continue to access the console even when the original
administrator leaves your organization or has their email address suspended. Only a single email address can be used as the
administrator contact.
To update the email address of the console administrator that was configured when the console was deployed, you must be
logged in as the console administrator. Navigate to the Users tab and click Configure on the IBM ID tile. In the panel that opens,
specify a new email address for the console administrator.
Configuring node logging

For debugging and analysis purposes, users can adjust default and custom "loggers" that control the "log level" of peer and
ordering node output for particular node functions or events. When the default Information log level for a component is not
sufficient for debugging, the console includes the ability to customize the logging level for the node and smart contracts.
Before you begin

A certificate from the peer or ordering node's TLS Certificate Authority (CA) must exist in the console wallet before you can
modify a log setting on the node. You need to have the enroll ID and secret available for at least one of the CA users.(The
user type does not matter.) Then, complete the following steps to generate the TLS certificate:
1. From the console, open the CA that is associated with the node. If you imported the node and its associated CA is not in
your console, you need to open the CA from the console where it resides.
2. Click the actions menu icon next to the user and then click Enroll identity.
3. On the side panel that opens, select TLS Certificate Authority from the Certificate Authority list.
4. Enter the Enroll secret that is associated with the Enroll ID for the user and click Next.
5. Provide a display name for the identity and then Export the identity to your file system.
6. Click Add identity to Wallet.
The TLS certificate now exists in your console wallet and you are ready to customize the node logging.
Customize logging
The process to customize the log settings is the same for a peer or ordering node. Open the node and click theSettings
icon. Click Log settings to open the panel.
Figure 1. Log settings
If you prefer a different default logging level than Information for all loggers on the node, select a new logging level ( Fatal ,
Panic , Error , Warning , Information , Debug ) from the Default logging level list. All loggers for the node will use use the
selected default log level unless overridden on this panel by providing the specific log levels for the loggers that you need for
debugging. There is no “master list” of loggers, and this panel does not validate whether the loggers exist. You can see the

names of the available loggers in the node logs, or you can read the Fabric source code to discover what loggers are available.
For ease of use, the following set of logging specification strings is provided and can be pasted into the Logging specification
field on the Advanced tab to customize the logging according to your debug needs:
Component Debug type Logging specification
Peer Smart info:dockercontroller,endorser,chaincode,chaincode.platform=debug

contracts
Peer Private data info:kvledger,ledgerstorage,transientstore,pvtdatastorage,gossip.privdata=debug
Peer Ledger and info:kvledger,lockbasedtxmgr,ledgerstorage,stateleveldb,statecouchdb,couchdb=debug

state
database
Peer Full debug, debug:cauthdsl,policies,msp,grpc,peer.gossip.mcs,gossip,leveldbhelper=info

with the
noisy
components
set to info
Ordering Full debug, debug:cauthdsl,policies,msp,grpc,orderer.consensus.etcdraft,orderer.common.cluster,ordere

node with the
noisy
components
set to info
Table 2. Useful logging specification strings
Important: A word on the logging specification syntax. Notice that the terms are separated by a colon. If a term does not
include a specific logger, for example info: then it is applied as the default log level, regardless of what is specified on
the Simple tab. This means that the string
info:dockercontroller,endorser,chaincode,chaincode.platform=debug sets the Default log level to
Information for all loggers and then the dockercontroller , endorser , chaincode ,and chaincode.platform
loggers are set to Debug .
Note that smart contract logging is the responsibility of the developer who defines the smart contract loggers. Debug your smart
contracts by providing the name of the smart contract logger and the desired log level on the Simple or Advanced tabs.
Tip: When you need to reset the logging for the node back to the Fabric default, delete any custom logger settings on the
Simple and Advanced tabs and set the Default log level to Information .
See the Fabric topic on Logging Control for more information. Read on for more information on how to view the node and smart
contract logs.
Viewing your logs

When you use the IBM Blockchain Platform console, you might need to view logs to debug an issue.
Note: In addition to the console and node logs that are available in the customer clusters, IBM keeps logs regarding IBM
Cloud account activity on the IBM Blockchain Platform instance. These logs are not available in customer clusters or their
containers. If you need these service management logs, open a support ticket.

Viewing your console logs
You can easily access the console logs if you need to debug problems that you encounter when you use the console or operate
your nodes. You can also set the logging level to increase or decrease the amount of logs that the console collects. The console
logs are collected separately from the node logs, which are collected by Kubernetes.
Navigate to the Settings tab in the console browser to change the logging settings. The console logs are collected from two
separate sources:
Client logging: These logs are collected when commands are sent from your browser to the console.
Server logging: These logs are collected when the console sends commands to your nodes and from the console
deployment. These logs include the Hyperledger Fabric logging output.
Set the amount of collected logs by using the drop-down list under each log type. For example,Error and Warning collect the
least amount of logs, while Debug and All collect the most.
You can view only the console logs if you are logged in as a console administrator. To view the logs from theSettings tab,
replace the word settings in the browser URL with api/v1/logs . For example, if your console URL is
localhost:3001/settings , you can view your logs by navigating to localhost:3001/api/v1/logs . Client and server logs
are collected in separate files. The most recent logs are at the top of the page.
Viewing your node logs

The logs of your peers, ordering nodes, and Certificate Authorities (CAs) are collected by the IBM Kubernetes Service or Red Hat
OpenShift. Use the steps below to view the logs of your nodes from the cluster where you deployed your IBM Blockchain
Platform network based on the type of cluster you are using.
Viewing nodes logs on an IBM Cloud Kubernetes Service cluster

To more easily locate your node logs, it is recommended to filter on the namespace that was used when the nodes were
deployed. To find the namespace, open any CA node in your console and click the Info and Usage icon. View the value of the API
URL. For example: https://n2734d0-soorg10524.ibpv2-cluster.us-south.containers.appdomain.cloud:7054 .
The namespace is the first part of the URL beginning with the letter n and followed by a random string of six alphanumeric
characters. So in the example above the value of the namespace is n2734d0 .
1. Open the IBM Cloud dashboard and navigate to the overview screen of your IBM Kubernetes Service cluster.
2. Above the cluster overview screen, click Kubernetes Dashboard.
3. Inside the Kubernetes dashboard, use the left navigation Namespace drop-down list to change to the namespace for your
IBM Blockchain Platform service instance that you discovered above.
4. On the left navigation, click Pods to view the list of node pods that you have deployed.
5. Click on a pod. Then click the View logs icon on the top menu to open the logs of your node. Above the logs, you can use
the drop-down menu after Logs from to view the logs from the different containers within the pod. For example, your peer
and the state database (CouchDB for example) run in different containers and generate different logs.
Viewing nodes logs on a Red Hat OpenShift 4.x cluster

See the Red Hat OpenShift documentation.
Viewing your smart contract container logs

If you encounter issues with your smart contract, you can view the smart contract logs to debug an issue. The process to view
the logs depends on whether your peer is running a Fabric v1.4 or v2.x image. The Fabric version that the peer is running is
visible when you click on a peer node in the console:

Figure 1.How to find peer fabric version
Hyperledger Fabric v2.x peer image
Important: While the terms "smart contract" and "chaincode" are often used interchangeably, "smart
contracts" refers to the business logic that governs transactions and access to its data, while "chaincode" refers to the
larger infrastructure of packages and other code that encompasses a smart contract.
If your peer is based on the Hyperledger Fabric v2.x image, you can run the following set of kubectl commands to view the smart
contract logs.
Find your cluster namespace
If you don't already know it, you need to find your Kubernetes cluster namespace. From the console, open any CA node and click
the Info and Usage icon. View the value of the API URL. For example: https://nf85a2a-soorg10524.ibpv2-cluster.us-
south.containers.appdomain.cloud:7054 . The namespace is the first part of the URL beginning with the letter n and
followed by a random string of six alphanumeric characters. So in the example above the value of the namespace is nf85a2a .
Find the smart contract pod
Next, get a list of all of the smart contract pods running in your cluster:
kubectl get po -n <NAMESPACE> | grep chaincode-execution | cut -d" " -f1 | xargs -I {} kubectl get po
{} -n <NAMESPACE> --show-labels
Replacing <NAMESPACE> with the name of your cluster namespace.
$ NAME READY STATUS RESTARTS

AGE LABELS
chaincode-execution-0a8fb504-78e2-4d50-a614-e95fb7e7c8f4 1/1 Running 0 14s
chaincode-id=javacc-1.1,peer-id=org1peer1
NAME READY STATUS RESTARTS AGE LABELS
chaincode-execution-f3cc736f-94ef-454d-8da3-362a50c653d9 1/1 Running 0 4m
chaincode-id=nodecc-1.1,peer-id=org1peer1
Your smart contract name and version is visible next to the chaincode-id .
View the logs
Then, to view the logs for a specific smart contract pod, run the command:
kubectl logs -f <SMART_CONTRACT_POD> -n <NAMESPACE>
Replace
<SMART_CONTRACT_POD> with the name of the pod where the smart contract is running.
<NAMESPACE> with the name of your cluster namespace.
For example:
kubectl logs -f chaincode-execution-0a8fb504-78e2-4d50-a614-e95fb7e7c8f4 -n nf85a2a
Hyperledger Fabric v1.4 peer image

Use these instructions when the peer is based on a Fabric v1.4 image.

Viewing smart contract logs on an IBM Cloud Kubernetes Service cluster
1. Open your Kubernetes dashboard, filter on your namespace, and click the peer pod where the smart contract is running.
2. Click the Logs link from your dashboard. By default it points to peer container.
3. Switch to the dind container by selecting it from the drop-down list.
All of your smart contract logs are visible in this window and can be downloaded using the download icon on the panel.
Viewing smart contract logs on a Red Hat OpenShift 4.x cluster
See the Red Hat OpenShift documentation. Access the logs for the peer pod where the smart contract is running and select the
dind container.
Using IBM Log Analysis to view the node logs

By default, the logs of your nodes are collected locally within your cluster. You can also use IBM Cloud services or a third-party
service to collect, store, and analyze the logs from your network. For more information, see Logging and monitoring cluster
health for the IBM Kubernetes Service or OpenShift. It is recommended that you take advantage of the IBM Log Analysis
service that allows you to easily parse the logs in real time. See this tutorial on using IBM Log Analysis with the IBM Blockchain
Platform.
Upgrading your nodes

The underlying IBM Hyperledger Fabric Docker images for the peer, CA, and ordering nodes might need to be updated over time,
for example, with security updates or to a new Fabric point release. The Upgrade available text on a node tile is the indicator
that such a patch is available and can be installed on the node whenever you are ready. Unless otherwise noted in the Release
notes, these upgrades are optional, but recommended. You cannot upgrade nodes that have been imported into the console.
Note: The best practice is to apply upgrades to one node at a time. While the upgrade is being applied, the node is
unavailable to process requests or transactions. Therefore, to avoid any disruption of service, whenever possible you
should ensure another node of the same type is available to process requests. Upgrading a node takes about a minute to
complete and when the update is complete, the node is ready to process requests.
For information about how to upgrade a node, check out Upgrading to the latest version of Fabric.
Kubernetes cluster expiration

If you are using a free IBM Cloud Kubernetes service cluster, it will expire after 30 days. When this happens, you can no longer
access your console. All of the associated nodes and certificates are deleted as well. You can have only one free cluster at a
time. Therefore, before you can create another blockchain service instance, you need to ensure that the expired cluster and its
associated service instance have been deleted from IBM Cloud. To confirm if they have already been deleted or to manually
delete these resources, follow these steps:
1. In your IBM Cloud dashboard, click the menu icon and open the Resource List.
2. Scroll to the Services twistie and expand it to view your service instance.
3. If your instance is listed, click the action menu for the service instance, thenDelete, to delete this service instance.
4. Scroll to the Kubernetes Clusters twistie and expand it to view your free cluster.
5. If your free cluster is listed, click the action menu for the cluster and then clickDelete to delete the free cluster.
When these actions are complete, you can follow the original steps to create a new Kubernetes cluster and blockchain service
instance from the IBM Cloud catalog page.

Important: Note that if you delete your Kubernetes cluster, you will still be charged for your IBM Blockchain Platform
service instance until you delete that as well.

When you deploy a node from the console, there are various advanced deployment options available for each node type. The
following topic provides more details about each of those options.
Target audience: This topic is designed for advanced network operators who are familiar with Hyperledger Fabric and are
responsible for creating, monitoring, and managing their components in the blockchain network.
What types of advanced deployment options are available?

The Build a network tutorial is useful for learning how to set up a basic network by using the IBM Blockchain Platform console.
But each use case has its own customizations that are required for a production network. When you are ready to explore
additional configuration settings, this topic describes the optional customizations that are available and the considerations they
require. The following table describes the types of customizations you can consider for each node type:
Description CA Peer Ordering node When to

perform
Resource Customize the allocated CPU and

allocations resources (CPU, memory can
memory, storage) for be adjusted
your node. during and
after
deployment.
Storage is
harder to
update after
deployment.
A best
practice is
to monitor
the storage
on your
nodes and
before they
become full,
stand up a
new larger
capacity
node to
replace the
node with
exhausted
storage.
Hardware Configure a node to Must be

Security generate and store the configured
Module node identity private key when the
(HSM) in an HSM for increased node is
security. deployed.
Certificate Customize the type of Must be

Authority database (SqlLite or configured
Database PostgreSQL) that will be when the
and used for storing CA data CA is
replication and configure replication deployed.
for high availability. You cannot
switch
databases
after the CA
is deployed.

Peer state Select whether you want All peers on
database the peer to use LevelDB a channel
or CouchDB for ledger must use
data. the same
state
database.
You cannot
change
databases
after the
peer is
deployed.
Deployment When your Kubernetes Must be

zone cluster is configured configured
selection across multiple zones, when the
you can choose the zone node is
where you want the deployed.
node to be deployed. You cannot
change
zones for a
node after
the node is
deployed.
Override Specify additional node Overrides

node configurations that are can be
configuration not available in the configured
console panels. when a
node is
deployed or
updated.
Table 1. Advanced deployment options
Before you begin
Important: Before attempting to deploy a node, it is the network operator's responsibility to monitor the cluster CPU,
memory, and storage usage, and ensure that adequate resources are available in the cluster for the node.
Allocating resources
Because your instance of the IBM Blockchain Platform console and your Kubernetes cluster do not communicate directly about
the resources that are available, the process for deploying components by using the console must follow this pattern:
1. Size the deployment that you want to make. The Resource allocation panels for the CA, peer, and ordering node in the
console offer default CPU, memory, and storage allocations for each node. You may need to adjust these values according
to your use case. If you are unsure, start with default allocations and adjust them as you understand your needs. Similarly,
the Resource reallocation panel displays the existing resource allocations. For a sense of how much storage and compute
you will need in your cluster, refer to the chart after step 3 that contains the current defaults for the peer, orderer, and CA:
2. Check whether you have enough resources in your Kubernetes cluster. If you are using a Kubernetes cluster that is
hosted in IBM Cloud, we recommend using the IBM Cloud Monitoring tool in combination with your IBM Cloud Kubernetes
dashboard. If you do not have enough space in your cluster to deploy or resize resources, you need to increase the size of
your cluster. For more information about how to increase the size of a cluster, see scaling Kubernetes or OpenShift
clusters. If you have enough space in your cluster, you can continue with step 3.
3. Use the console to deploy or resize your node. If your Kubernetes pod is large enough to accommodate the new size of
the node, the reallocation should proceed smoothly. If the worker node that the pod is running on is running out of
resources, you can add a new larger worker node to your cluster and then delete the existing working node.

(GB)

CA 0.1 0.2 20
Operator 0.1 0.2 0
Console 1.2 2.4 10
Table 2. Default resources for nodes on IBM Blockchain Platform
** Actual VPC allocations are visible in the blockchain console when a node is deployed.
While users of a free cluster must use default sizes for the containers associated with their nodes, users of paid clusters can set
these values while the node is being created by clicking the Resource allocation box during the creation of their nodes. If this
box is not checked, the default resource allocations, which can be seen below, will be used.
For cases when a user wants to minimize charges without stopping or deleting a node, it is possible to scale the node down to a
minimum of 0.001 CPU (1 milliCPU). Note that the node will not be functional when using this amount of CPU.
Tip: While the figures in this topic endeavor to be precise, be aware that there are times when a node may not deploy
even when it appears that you have enough space in your cluster. Make sure to reference your Kubernetes dashboard to
see when components deploy and for error messages when they don't. In cases where a component doesn't deploy for a
lack of resources, even if there seems to be enough space in the cluster, you will likely have to deploy additional cluster
resources for the component to deploy.
The Resource allocation panel in the console provides default values for the various fields that are involved in creating a node.
These values are chosen because they represent a good way to get started. However, every use case is different. While this topic
provides guidance for ways to think about these values, it ultimately falls to the user to monitor their nodes and find sizings that
work for them. Therefore, barring situations in which users are certain that they need values different from the defaults, a
practical strategy is to use these defaults at first and adjust them later. For an overview of performance and scale of Hyperledger
Fabric, which the IBM Blockchain Platform is based on, see Answering your questions on Hyperledger Fabric performance and
scale.
Important: After you have deployed the node, you need to monitor the resource consumption of the node. Configure a
monitoring tool such as IBM Cloud Monitoring to observe the nodes and ensure that adequate resources are available to
the node containers when processing transactions.
All of the containers that are associated with a node have CPU and memory, while certain containers that are associated with
the peer, ordering node, and CA also have storage. For more information about storage, see Persistent storage considerations.
Note that when your Kubernetes cluster is configured to use any of the IBM Cloud storage classes, the smallest storage amount
that can be allocated to a node is 20Gi.
You are responsible for monitoring your CPU, memory, and storage consumption in your cluster. If you do happen to request
more resources for a blockchain node than are available, the node will not start. However, existing nodes will not be affected. If
you are using IBM Cloud as your cloud provider, CPU and memory can be changed by using the console and Kubernetes cluster

on IBM Cloud dashboard. To expand available storage capacity, refer to the follow links for more information:
IBM file storage

Portworx
Block storage
Every node has a gRPC web proxy container that bootstraps the communication layer between the console and a node. This
container has fixed resource values and is included on the Resource allocation panel to provide an accurate estimate of how
much space is required on your Kubernetes cluster in order for the node to deploy. Because the values for this container cannot
be changed, we will not discuss the gRPC web proxy in the following sections.
CA deployment
When you deploy a CA, the following advanced deployment options are available:
Database and replica sets - Configure a CA for zero downtime.

Deployment zone selection - In a multi-zone cluster, select the zone where the node is deployed.
Resource allocation - Configure the CPU, memory, and storage for the node.
Hardware Security Module - Configure the CA to use an HSM to generate and store private keys.
CA configuration override - Choose this option when you want to override CA configuration settings.
Database and replica sets

Because redundancy is the key to ensuring that when a node goes down another node is able to continue to process requests,
you have the option to configure replica sets for CA nodes. For a complete understanding of what replica sets are and how they
can be configured for a CA, see this topic on Building a high availability Certificate Authority (CA).
Deployment zone selection

If your Kubernetes cluster is configured across multiple zones, when you deploy a CA you have the option of selecting which
zone the CA is deployed to. Check the Advanced deployment option that is labeled Deployment zone selection to see the list of
zones that is currently configured for your Kubernetes cluster.
Sizing a CA during creation

Unlike peers and ordering nodes, which are actively involved in the transaction process, CAs are involved only in the registration
and enrollment of identities, and in the creation of an MSP. This means that they require less CPU and memory. To stress a CA, a
user would need to overwhelm it with requests (likely using APIs and a script), or have issued so many certificates that the CA
runs out of storage. Under typical operations, neither of these things should happen, though as always, these values should
reflect the needs of a particular use case.
The CA has only one associated container that we can adjust:
CA container: Encapsulates the internal CA processes, such as registering and enrolling nodes and users, as well as
storing a copy of every certificate it issues.
As we noted in our section on Considerations before you deploy a node, it is recommended to use the defaults for the CA
container and adjust them later when it becomes apparent how they are being utilized by your use case.
Resources Condition to increase
CA container CPU and memory When you expect that your CA will be bombarded with registrations and enrollments.
CA storage When you plan to use this CA to register a large number of users and applications.

For more details on the resource allocation panel in the console see Allocating resource.
Creating highly available CAs

For information about creating highly available CAs through the use of replica sets, see how to configure CA replica sets.
Customizing a CA configuration
In addition to the CA settings that are provided in the console when you provision a CA, you have the option to override some of
the settings. If you are familiar with the Hyperledger Fabric CA server, these settings are configured in the fabric-ca-server-
config.yaml file when a CA is deployed. The IBM Blockchain Platform console configures these fields for you with default
settings. Therefore, many of these fields are not exposed by the console. But the console also includes a panel where you can
edit a JSON to override a set of these parameters before a CA is deployed.
Note: The ability to override the CA configuration by using the console or APIs is available only in paid clusters.
Why would I want to override a CA configuration?

You can use the console to configure resource allocation, HSM, or the CA database and then edit the generated JSON adding
additional parameters and fields for your use case. For example, you might want to register additional users with the CA when
the CA is created, or specify custom affiliations for your organizations. You can also customize the CSR names that are used
when certificates are issued by the CA or add affiliations. These are just a few suggestions of customizations you might want to
make but the full list of parameters is provided below. This list contains all of fields that can be overridden by editing the JSON
when a CA is deployed. For more information about what each field is used for you can refer to the Fabric CA documentation.
{
"ca": {
"cors": {
"enabled": false,
"origins": [
"*"
]
},
"debug": false,
"crlsizelimit": 512000,
"tls": {
"certfile": null,
"keyfile": null,
"clientauth": {
"type": "noclientcert",
"certfiles": null
}
},
"ca": {
"keyfile": null,
"certfile": null,
"chainfile": null
},
"crl": {
"expiry": "24h"
},
"registry": {
"identities": [
{
"name": "<<<adminUserName>>>",
"pass": "<<<adminPassword>>>",
"type": "client",
"attrs": {

"hf.Revoker": true,
"hf.GenCRL": true,
}
}
]
},
"db": {
"type": "sqlite3",
"datasource": "fabric-ca-server.db",
"tls": {
"enabled": false,
"certfiles": null,
"client": {
"certfile": null,
"keyfile": null
}
}
},
"affiliations": {
"ibp": []
},
"csr": {
"cn": "ca",
"keyrequest": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "US",
"ST": "North Carolina",
"L": null,
"O": "Hyperledger",
"OU": "Fabric"
}
],
"hosts": [
"<<<MYHOST>>>",
"localhost"
],
"ca": {
"expiry": "131400h",
"pathlength": "<<<PATHLENGTH>>>"
}
},
"idemix": {
"rhpoolsize": 1000,
"nonceexpiration": "15s",
"noncesweepinterval": "15m"
},
"bccsp": {
"default": "SW",
"sw": {
"hash": "SHA2",
"security": 256,
"filekeystore": null
}
},
"intermediate": {
"parentserver": {
"url": null,
"caname": null
},
"enrollment": {
"hosts": null,
"profile": null,

"label": null
},
"tls": {
"certfiles": null,
"client": {
"certfile": null,
"keyfile": null
}
}
},
"cfg": {
"identities": {
"passwordattempts": 10,
"allowremove": true
}
},
"metrics": {
"provider": "prometheus",
"statsd": {
"network": "udp",
"address": "127.0.0.1:8125",
"writeInterval": "10s",
"prefix": "server"
}
}
}
}
Providing your own customizations when you create a CA

After you click Create a CA on the nodes tab and step through the CA configuration panels, you can clickEdit configuration on
the Summary panel to view and edit the JSON . Note that if you do not select any advanced options in the console, then those
advanced configuration settings are not included in the JSON , but you can insert them yourself, using the elements provided in
JSON above.
Alternatively, if you do check any of the advanced options when you configure the CA, those settings are included in the JSON on
the Summary panel and can be additionally customized.
Any edits that you make to the JSON override what was specified in the console UI. For example, if you specified a Maximum
enrollments value of 10 in the console, but then provided the maxenrollments value of -1 in the JSON , then the value in
the JSON file is used when the CA is deployed. It is the settings that are visible in the JSON on the Summary page that are used
when the CA is deployed.
Here is an example of the minimum required JSON parameters for any override when a CA is deployed.
{
"ca": {
"csr": {
"cn": "<COMMONNAME>",
"keyrequest": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "US",
"L": "Location",
"O": "Hyperledger",
"OU": "Fabric"
}
],
"hosts": [
"<HOSTNAME>"

],
"ca": {
"expiry": "131400h",
"pathlength": 1024
}
},
"debug": false,
"registry": {
"identities": [
{
"name": "<ADMIN_ID>",
"pass": "<ADMIN_PWD>",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}
]
},
"affiliations": {
"ibp": []
},
}
}
You can insert additional fields or modify the JSON that is visible in the Configuration JSON box. For example, if you want to
deploy a CA and override only the csr names values, you can edit the values in the JSON . But if you wanted to change the
value of the passwordattempts field you would insert it into the JSON as follows:
{
"ca": {
"csr": {
"cn": "<COMMONNAME>",
"keyrequest": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "US",
"L": "Location",
"O": "Hyperledger",
"OU": "Fabric"
}
],
"hosts": [
"<HOSTNAME>"
],
"ca": {
"expiry": "131400h",
"pathlength": 1024
}
},
"debug": false,
"registry": {
"identities": [
{
"name": "<ADMIN_ID>",

"pass": "<ADMIN_PWD>",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}
]
},
"affiliations": {
"ibp": []
},
"cfg": {
"identities": {
"passwordattempts": 3
}
}
}
}
This snippet is provided only as an example of what the modified JSON would resemble. Do not copy and edit this snippet, as it
does not contain the custom values for your configuration. Rather, edit the JSON from your console Configuration JSON box
because it includes the settings for your node.
Considerations when including certificates

Unlike in the Fabric CA configuration file, where specification of a certfile includes a file path and certificate name, in this
case you need to base64 encode the certificate file (or a concatenated chain of certificates) and then paste the resulting string
into the CA JSON override. To convert a certificate file into base64 format, run the following command:
cat <CERT_FILE> | base64 $FLAG
Replace <CERT_FILE> with the name of the file that you need to encode.
Paste the resulting string into the CA JSON override.
Modifying CA settings after deployment

After a CA is deployed, a subset of the fields can be updated as well. Click the CA tile in the console and then theSettings icon to
open a side panel. Click Edit configuration JSON (Advanced) to override the CA settings. The JSON in the Current configuration
box contains the current settings for the CA. Not all of these values can be overridden.
Only the following fields can be updated:
{
"ca":{
"cors": {
"enabled": false,
"origins": [
"*"
]
},
"debug": false,
"crlsizelimit": 512000,
"tls": {
"certfile": null,
"keyfile": null,

"clientauth": {
"type": "noclientcert",
"certfiles": null
}
},
"crl": {
"expiry": "24h"
},
"db": {
"type": "sqlite3",
"datasource": "fabric-ca-server.db",
"tls": {
"enabled": false,
"certfiles": null,
"client": {
"certfile": null,
"keyfile": null
}
}
},
"csr": {
"cn": "ca",
"keyrequest": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "US",
"L": "Location",
"O": "Hyperledger",
"OU": "Fabric"
}
],
"hosts": [
"<<<MYHOST>>>",
"localhost"
],
"ca": {
"expiry": "131400h",
"pathlength": "<<<PATHLENGTH>>>"
}
},
"idemix": {
"rhpoolsize": 1000,
"nonceexpiration": "15s",
"noncesweepinterval": "15m"
},
"bccsp": {
"default": "SW",
"sw": {
"hash": "SHA2",
"security": 256,
"filekeystore": null
}
},
"cfg": {
"identities": {
"allowremove": true
}
},
"metrics": {
"provider": "prometheus",
"statsd": {
"network": "udp",
"address": "127.0.0.1:8125",

"prefix": "server"
}
}
}
}
Paste the modified JSON that contains only the parameters that you want to update into theConfiguration JSON box. For
example, if you only needed to update the value for the passwordattempts field you would paste in this JSON :
{
"ca": {
"cfg": {
"identities": {
"passwordattempts": 3
}
}
}
}
If you need to enable deletion of registered users from a CA you would insert "allowremove": true into the JSON as follows:
{
"ca": {
"cfg": {
"identities": {
"allowremove": true
}
}
}
}
Note: The ability to update a CA configuration is not available for CAs that have been imported into the console.
Peer deployment
When you deploy a peer, the following advanced deployment options are available:
State database - Choose the database for your peers where ledger transactions are stored.
External Certificate Authority configuration - Use certificates from a third-party CA.
Hardware Security Module - Configure the peer to use an HSM to generate and store private keys.
Peer configuration override - Choose this option when you want to override peer configuration.
Important: You also have the ability to choose the version of Fabric that will be used to deploy your peer. It is
recommended to always choose the latest version, as this version will have the latest fixes and improvements. However,
note that you might have to re-vendor your smart contract if it was written in Golang. For more information, see Write and
package your smart contract.
State database
During the creation of a peer, it is possible to choose between two state database options:LevelDB and CouchDB. Recall that
the state database keeps the latest value of all of the keys (assets) stored on the blockchain. For example, if a car has been
owned by Varad and then Joe, the value of the key that represents the ownership of the car would be "Joe".
Because it can be useful to perform rich queries against the state database (for example, searching for every red car with an

automatic transmission that is owned by Joe), users will often choose a Couch database, which stores data as JSON objects.
LevelDB, on the other hand, only stores information as key-value pairs, and therefore cannot be queried in this way. Users must
keep track of block numbers and query the blocks directly (or within a range of block numbers), and parse the information.
However, LevelDB is also faster than CouchDB, though it does not support database indexing (which helps performance).
This support for rich queries is why CouchDB is the default database unless a user selects the State database selection box
during the process of adding a peer selects LevelDB on the subsequent tab.
Important: Because the data is modeled differently in a Couch database than in a Level database,the peers in a channel
must all use the same database type. If data written for a Level database is rejected by a Couch database (which can
happen, as CouchDB keys have certain formatting restrictions as compared to LevelDB keys), a state fork would be
created between the two ledgers. Therefore, take extreme care when joining a channel to know the database type
supported by the channel. It might be necessary to create a new peer that uses the appropriate database type and join it
to the channel. Note that the database type cannot be changed after a peer has been deployed.

If your Kubernetes cluster is configured across multiple zones, when you deploy a peer you have the option of selecting which
zone the peer is deployed to. Check the Advanced deployment option that is labeled Deployment zone selection to see the list
of zones that is currently configured for your Kubernetes cluster.
If you are deploying a redundant node (that is, another peer when you already have one), it is a best practice to deploy this node
into a different zone. You can determine the zone that the other node was deployed to by opening the tile of the node and
looking under the Node location. Alternatively, you can use the APIs to deploy a peer or orderer to a specific zone. For more
information on how to do this with the APIs, see Creating a node within a specific zone.
If multizone-capable storage is configured for your Kubernetes cluster, when a zone failure occurs, the nodes can come up in
another zone with their associated storage intact, ensuring high availability of the node. In order to leverage this capability with
the IBM Blockchain Platform, you need to configure your cluster to use SDS (Portworx) storage. And when you deploy a peer,
select the advanced deployment option labeled Deployment zone selection and then select Across all zones. To learn more
about multizone-capable storage, see the Comparison of persistent storage options for multizone clusters on OpenShift or IBM
Cloud Kubernetes service.
Sizing a peer during creation

The peer pod has four containers that can be adjusted:
Peer container: Encapsulates the internal peer processes (such as validating transactions) and the blockchain (in other
words, the transaction history) for all of the channels it belongs to. Note that the storage of the peer also includes the
smart contracts that are installed on the peer.
CouchDB container: Where the state databases of the peer are stored. Recall that each channel has a distinct state
database.
Smart contract container: Recall that during a transaction, the relevant smart contract is "invoked" (in other words, run).
Note that all smart contracts that you install on the peer will run in a separate container inside your peer pod, which is
known as a Docker-in-Docker container.
Smart contract launcher container: Used to launch a separate pod for each smart contract, eliminating the need for a
Docker-in-Docker container in the peer pod. Note that the smart contract launcher container is not where smart contracts
actually run, and is therefore given a smaller default resource than the "smart contracts" container that used to be
deployed along with a peer. It only exists to help create the pods where smart contracts run. You must make your own
allowances in your deployment for the containers for smart contracts, as the pods spun up by the smart contract launcher
are not bound by strict resource limitations. The pod will use as many resources as it needs depending on the size of a
smart contract and the processing load it encounters. For more information, see Resource Quotas.
Important: Note that a separate pod will be created for each smart contract that is installed on each peer, even if you

have multiple peers on the same channel that have all installed the same smart contract. So if you have three peers on a
channel, and install a smart contract on each one, you will have three smart contract pods running. However, if these
three peers are on more than one channel using the exact same smart contract, you will still only have three pods
running. These smart contract pods will not be deleted if you delete the peer. You must delete them separately.
The peer also includes a gRPC web proxy container, you cannot adjust the compute for this container.
As we noted in our section on Considerations before you deploy a node, it is recommended to use the defaults for these peer
containers and adjust them later when it becomes apparent how they are being utilized by your use case.
Peer When you anticipate a high transaction throughput right away.

container
CPU and
memory
Peer When you anticipate installing many smart contracts on this peer and to join it to many channels. Recall that
storage this storage will also be used to store smart contracts from all channels the peer is joined to. Keep in mind
that we estimate a "small" transaction to be in the range of 10,000 bytes (10k). As the default storage is
100G, this means that as many as 10 million total transactions will fit in peer storage before it will need to be
expanded (as a practical matter, the maximum number will be less than this, as transactions can vary in size
and the number does not include smart contracts). While 100G might therefore seem like much more storage
than is needed, keep in mind that storage is relatively inexpensive, and that the process for increasing it is
more difficult (require command line) than increasing CPU or memory.
CouchDB When you anticipate a high volume of queries against a large state database. This effect can be mitigated
container somewhat by using indexes. Nevertheless, high volumes might strain CouchDB, which can lead to query and
CPU and transaction timeouts.
memory
CouchDB When you expect high throughput on many channels and don't plan to use indexes. However, like the peer
(ledger storage, the default CouchDB storage is 100G, which is significant.
data)
storage
Smart When you expect a high throughput on a channel, especially in cases where multiple smart contracts will be
contract invoked at the same time. You should also increase the resource allocation of your peers if your smart
container contracts are written in JavaScript or TypeScript.
CPU and
memory
Smart Because the smart contract launcher container streams logs from smart contracts back to a peer, the more
contract smart contracts are running the greater the load on the smart contract launcher.
launcher
container
CPU and
memory
Important: The IBM Blockchain Platform supports smart contracts that are written in JavaScript, TypeScript, Java, and
Go. When you are allocating resources to your peer node, it is important to note that JavaScript and TypeScript smart
contracts require more resources than contracts written in Go. The default storage allocation for the peer container is
sufficient for most smart contracts. However, when you instantiate a smart contract, you should actively monitor the
resources consumed by the pod that contains the smart contract in your cluster by using a tool like IBM Cloud Monitoring
to ensure that adequate resources are available.
Customizing a peer configuration

In addition to the peer settings that are provided in the console when you provision a peer, you have the extra option to override

some of the peer settings. If you are familiar with Hyperledger Fabric, these settings are configured in the peer configuration
core.yaml file when a peer is deployed. The IBM Blockchain Platform console configures these fields for you using default
settings and many of these fields are not exposed by the console. But the console also includes a panel where you can provide a
JSON to override a set of these parameters before a peer is deployed. You can find the peer configuration JSON and an example
of how to use the configuration override to customize your deployment in the sections below.
Note: The ability to override the peer configuration by using the console or APIs is available only in paid clusters.
Why would I want to override a peer configuration?

A common use case is to override some of the default timeouts, or peer private data settings. You can also customize the gossip
configuration. The full list of available overrides is provided below, which contains all fields that can be overridden by editing the
JSON when a peer is deployed from the console. For more information on each field, refer to the Fabric sample peer
configuration file options.
{
"peer": {
"id": "jdoe",
"networkId": "dev",
"keepalive": {
"minInterval": "60s",
"client": {
"interval": "60s",
"timeout": "20s"
},
"deliveryClient": {
"interval": "60s",
"timeout": "20s"
}
},
"gossip": {
"useLeaderElection": true,
"orgLeader": false,
"membershipTrackerInterval": "5s",
"maxBlockCountToStore": 100,
"maxPropagationBurstLatency": "10ms",
"maxPropagationBurstSize": 10,
"propagateIterations": 1,
"propagatePeerNum": 3,
"pullInterval": "4s",
"pullPeerNum": 3,
"requestStateInfoInterval": "4s",
"publishStateInfoInterval": "4s",
"stateInfoRetentionInterval": null,
"publishCertPeriod": "10s",
"skipBlockVerification": false,
"dialTimeout": "3s",
"connTimeout": "2s",
"recvBuffSize": 20,
"sendBuffSize": 200,
"digestWaitTime": "1s",
"requestWaitTime": "1500ms",
"responseWaitTime": "2s",
"aliveTimeInterval": "5s",
"aliveExpirationTimeout": "25s",
"reconnectInterval": "25s",
"election": {
"startupGracePeriod": "15s",
"membershipSampleInterval": "1s",
"leaderAliveThreshold": "10s",
"leaderElectionDuration": "5s"
},
"pvtData": {

"pullRetryThreshold": "60s",
"transientstoreMaxBlockRetention": 1000,
"pushAckTimeout": "3s",
"btlPullMargin": 10,
"reconcileBatchSize": 10,
"reconcileSleepInterval": "1m",
"reconciliationEnabled": true,
"skipPullingInvalidTransactionsDuringCommit": false
},
"state": {
"enabled": true,
"checkInterval": "10s",
"responseTimeout": "3s",
"batchSize": 10,
"blockBufferSize": 100,
"maxRetries": 3
}
},
"authentication": {
"timewindow": "15m"
},
"BCCSP": {
"Default": "SW",
"SW": {
"Hash": "SHA2",
"Security": 256,
"FileKeyStore": {
"KeyStore": null
}
},
"PKCS11": {
"Library": null,
"Label": null,
"Pin": null,
"Hash": null,
"Security": null,
"FileKeyStore": {
"KeyStore": null
}
}
},
"client": {
"connTimeout": "3s"
},
"deliveryclient": {
"reconnectTotalTimeThreshold": "3600s",
"reConnectBackoffThreshold": "3600s",
"addressOverrides": null
},
"adminService": null,
"validatorPoolSize": null,
"discovery": {
"enabled": true,
"authCacheEnabled": true,
"authCacheMaxSize": 1000,
"authCachePurgeRetentionRatio": 0.75,
"orgMembersAllowedAccess": false
}
},
"chaincode": {
"startuptimeout": "300s",
"executetimeout": "30s",
"logging": {
"level": "info",
"shim": "warning",
"format": "%{color}%{time:2006-01-02 15:04:05.000 MST} [%{module}] %{shortfunc} -> %
{level:.4s} %{id:03x}%{color:reset} %{message}"
}

},
"metrics": {
"provider": "disabled",
"statsd": {
"network": "udp",
"address": "127.0.0.1:8125",
"prefix": null
}
}
}
Providing your own customizations when you create a peer

After you click Create a peer on the nodes tab and step through the peer configuration panels, you can clickEdit configuration
on the Summary panel to view and edit the JSON . Note that if you do not select any advanced options in the console, then the
generated JSON is empty, but you can still insert your own customizations.
Alternatively, if you do check any of the advanced options when you configure the peer, those settings are included in the JSON
on the Summary panel and can be additionally customized with other fields as needed. Any edits that you make will override
what was specified in the console. For example, if you selected to use a LevelDB as the state database, but then overrode the
setting to use CouchDB as the state database in the JSON , then the CouchDB database settings would be used when the peer is
deployed. The override settings that are visible in the JSON on the Summary page are what is used when the peer is deployed.
You don't need to include the entire set of available parameters in the JSON , only the advanced deployment options that you
selected in the console along with the parameters that you want to override. For example, if you want to deploy a peer and
override the chaincode startup timeout and specify a different port for the statsd address , you would paste in the
following JSON :
{
"peer": {
"chaincode": {
"startuptimeout": "600s"
}
},
"metrics": {
"statsd": {
"address": "127.0.0.1:9443"
}
}
}
Modifying peer settings after deployment

After a peer is deployed, a subset of the fields can be updated as well. Click the peer tile in the console and then theSettings
icon to open a side panel. Click Edit configuration JSON (Advanced) to open the panel where you can override the peer settings.
The JSON in the Current configuration box contains the current settings for the peer. Not all of these values can be overridden
after the peer is deployed. A subset of these parameters can be overridden by pasting a JSON with the overrides into the
Configuration JSON box. Again, you don't need to include the entire set of parameters from theCurrent configuration JSON ,
only paste the parameters you want to override into the Configuration JSON box.
The following subset of parameters can be overridden after a peer is deployed:
{
"peer": {
"id": "jdoe",
"networkId": "dev",
"keepalive": {
"minInterval": "60s",
"client": {

"interval": "60s",
"timeout": "20s"
},
"deliveryClient": {
"interval": "60s",
"timeout": "20s"
}
},
"gossip": {
"useLeaderElection": true,
"orgLeader": false,
"membershipTrackerInterval": "5s",
"maxBlockCountToStore": 100,
"maxPropagationBurstLatency": "10ms",
"maxPropagationBurstSize": 10,
"propagateIterations": 1,
"propagatePeerNum": 3,
"pullInterval": "4s",
"pullPeerNum": 3,
"requestStateInfoInterval": "4s",
"publishStateInfoInterval": "4s",
"stateInfoRetentionInterval": null,
"publishCertPeriod": "10s",
"skipBlockVerification": false,
"dialTimeout": "3s",
"recvBuffSize": 20,
"sendBuffSize": 200,
"digestWaitTime": "1s",
"requestWaitTime": "1500ms",
"responseWaitTime": "2s",
"aliveTimeInterval": "5s",
"aliveExpirationTimeout": "25s",
"reconnectInterval": "25s",
"election": {
"startupGracePeriod": "15s",
"membershipSampleInterval": "1s",
"leaderAliveThreshold": "10s",
"leaderElectionDuration": "5s"
},
"pvtData": {
"pullRetryThreshold": "60s",
"transientstoreMaxBlockRetention": 1000,
"pushAckTimeout": "3s",
"btlPullMargin": 10,
"reconcileBatchSize": 10,
"reconcileSleepInterval": "1m",
"reconciliationEnabled": true,
"skipPullingInvalidTransactionsDuringCommit": false
},
"state": {
"enabled": true,
"checkInterval": "10s",
"responseTimeout": "3s",
"batchSize": 10,
"blockBufferSize": 100,
"maxRetries": 3
}
},
"authentication": {
"timewindow": "15m"
},
"client": {
"connTimeout": "3s"
},
"deliveryclient": {
"reconnectTotalTimeThreshold": "3600s",
"reConnectBackoffThreshold": "3600s",

"addressOverrides": null
},
"adminService": null,
"validatorPoolSize": null,
"discovery": {
"enabled": true,
"authCacheEnabled": true,
"authCacheMaxSize": 1000,
"authCachePurgeRetentionRatio": 0.75,
"orgMembersAllowedAccess": false
}
},
"chaincode": {
"startuptimeout": "300s",
"executetimeout": "30s",
"logging": {
"level": "info",
"shim": "warning",
"format": "%{color}%{time:2006-01-02 15:04:05.000 MST} [%{module}] %{shortfunc} -> %
{level:.4s} %{id:03x}%{color:reset} %{message}"
}
},
"metrics": {
"provider": "disabled",
"statsd": {
"network": "udp",
"address": "127.0.0.1:8125",
"prefix": null
}
}
}
example, if you only need to update the value for the executetimeout field you would paste this JSON into the Configuration
JSON box:
{
"chaincode": {
"executetimeout": "30s"
}
}
Note: The ability to update override settings for a peer configuration is not available for peers that have been imported
into the console.
Ordering node deployment

When you deploy an ordering node, the following advanced deployment options are available:
Number of ordering nodes - Decide how many ordering nodes are needed.
External Certificate Authority configuration - Use certificates from a third-party CA.
Hardware Security Module - Configure the ordering node to use an HSM to generate and store private keys.
Orderer configuration override - Choose this option when you want to override ordering node configuration.
Important: You also have the ability to choose the version of Fabric that will be used to deploy your ordering nodes. It is
recommended to always choose the latest version, as this version will have the latest fixes and improvements. Note that it
is currently not possible to enable any v2.0 Fabric capabilities.

Number of ordering nodes
In Raft, a majority of the total number of nodes must be available for the ordering service to function (this is known as achieving
a "quorum" of nodes). In other words, if you have one node, you need that node available to have a quorum, because the
majority of one is one. While satisfying the quorum makes sure that the ordering service is functioning, production networks also
have to think about deployment configurations that are highly available (in other words, configurations in which the loss of a
certain number of nodes can be tolerated by the system). Typically, this means tolerating the loss of two nodes: one node going
down during a normal maintenance cycle, and another going down for any other reason (such as a power outage or error).
This is why, by default, the console offers two options: one node or five nodes. Recall that the majority of five is three. This
means that in a five node configuration, the loss of two nodes can be tolerated. Users who know that they will be deploying a
production solution should therefore choose the five node option.
However many nodes a user chooses to deploy, they have the ability to add more nodes to their ordering service. For more
information, see Adding and removing ordering service nodes.

If your Kubernetes cluster is configured across multiple zones, when you deploy an ordering node you have the option of
selecting which zone the node is deployed to. Check the Advanced deployment option that is labeled Deployment zone
selection to see the list of zones that is currently configured for your Kubernetes cluster.
For a five node ordering service, these nodes will be distributed into multiple zones by default, depending on the relative space
available in each zone. You also have the ability to distribute a five node ordering service yourself by clearing the default option
to have the zones that are chosen for you and distributing these nodes into the zones you have available. You can check which
zone a node was deployed to by opening the tile of the node and looking under the Node location. Alternatively, you can use the
APIs to deploy an ordering node to a specific zone. For more information on how to do this with the APIs, see Creating a node
within a specific zone.
If multizone-capable storage is configured for your Kubernetes cluster when a zone failure occurs, the nodes can come up in
another zone, with their associated storage intact, ensuring high availability of the node. In order to leverage this capability with
the IBM Blockchain Platform, you need to configure your cluster to use SDS (Portworx) storage. And when you deploy an
ordering service or an ordering node, select the advanced deployment option labeled Deployment zone selection and then
select Across all zones. To learn more about multizone-capable storage, see the Comparison of persistent storage options for
multizone clusters on OpenShift or IBM Cloud Kubernetes service.
Sizing an ordering node during creation

Because ordering nodes do not maintain a copy of the state DB, they require fewer containers than peers do. However, they do
host the blockchain (the transaction history) because the blockchain is where the channel configuration is stored, and the
ordering service must know the latest channel configuration to perform its role.
Similar to the CA, an ordering node has only one associated container that we can adjust (if you are deploying a five-node
ordering service, you will have five separate ordering node containers, as well as five separate gRPC containers):
Ordering node container: Encapsulates the internal orderer processes (such as validating transactions) and the
blockchain for all of the channels it hosts.
As we noted in our section on Considerations before you deploy a node, it is recommended to use the defaults for the ordering
node container and adjust them later as it becomes apparent how they are being utilized.

Ordering When you anticipate a high transaction throughput right away.
node
container
CPU and
memory
Ordering When you anticipate that this ordering node will be part of an ordering service on many channels. Recall
node storage that the ordering service keeps a copy of the blockchain for every channel they host. The default storage
of an ordering node is 100G, same as the container for the peer itself.
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, a
total of 1.75 CPU, 3.5 GB of memory, and 500 GB of storage for the five Raft nodes. A 4 CPU Kubernetes single worker node
cluster is the minimum recommended to allow enough CPU for the ordering service cluster and any other nodes you deploy.
Important: If an ordering service is overstressed, it might hit timeouts and start dropping transactions, requiring
transactions to be resubmitted. This causes much greater harm to a network than a single peer struggling to keep up. In a
Raft ordering service configuration, an overstressed leader node might stop sending heartbeat messages, triggering a
leader election, and a temporary cessation of transaction ordering. Likewise, a follower node might miss messages and
attempt to trigger a leader election where none is needed.
Customizing an ordering service configuration

In addition to the ordering node settings that are provided in the console when you provision an ordering node, you have the
option to override some of the default settings. If you are familiar with Hyperledger Fabric, these settings are configured in the
orderer.yaml file when an ordering node is deployed. The IBM Blockchain Platform console configures these fields for you
using default settings so many of these fields are not exposed by the console. You can find the orderer configuration JSON and
an example of how to use the configuration override to customize your deployment in the sections below.
Note: The ability to override the ordering service configuration by using the console or APIs is available only in paid
clusters.
Why would I want to override an ordering service configuration?

The need to customize the ordering node configuration is less common than the peer or CA. A common use case could be to
override default timeouts or the default HSM settings. This list contains all of fields that can be overridden by editing the JSON
when an ordering node is deployed from the console. For more information about what each field is used for you can refer to the
Fabric sample orderer configuration file options.
{
"General": {
"Keepalive": {
"ServerMinInterval": "60s",
"ServerInterval": "7200s",
"ServerTimeout": "20s"
},
"BCCSP": {
"Default": "SW",
"SW": {
"Hash": "SHA2",
"Security": 256,
"FileKeyStore": {
"KeyStore": null
}
}

},
"Authentication": {
"TimeWindow": "15m"
}
},
"Debug": {
"BroadcastTraceDir": null,
"DeliverTraceDir": null
},
"Metrics": {
"Provider": "disabled",
"Statsd": {
"Network": "udp",
"Address": "127.0.0.1:8125",
"WriteInterval": "30s",
"Prefix": null
}
}
}
Providing your own customizations when you create an ordering service

After you click Add ordering service on the nodes tab and step through the ordering service configuration panels, you can click
Edit configuration JSON on the Summary panel to view and edit the JSON . Note that if you do not select any advanced options
in the console, then the generated JSON is empty, but you can insert your own customizations.
Alternatively, if you do check any of the advanced options when you configure the ordering service, those settings are included in
the JSON on the Summary panel. Any edits that you make to the JSON override what was specified in the console. You can insert
additional fields or modify the generated JSON . The overrides that are visible in the JSON on the Summary page are what is
used to override the default settings when the ordering node is deployed. If you are deploying multiple ordering nodes, then
the overrides are applied to each ordering node.
You don't need to include the entire set of available parameters in the JSON , only any advanced deployment options that you
selected in the console along with the parameters that you want to override. For example, if did not select any advanced options
in the console and you want to deploy the ordering nodes with your own value for the ServerTimeout and the statsd
address port, you would paste the following JSON into the Configuration JSON box:
{
"General": {
"Keepalive": {
}
},
"metrics": {
"statsd": {
"address": "127.0.0.1:9446"
}
}
}
Modifying ordering node settings after deployment

After an ordering node is deployed, a subset of the fields can be updated as well. Click the ordering service tile in the console
and select the ordering node, then click the Settings icon to open a side panel where you can modify the JSON . The JSON in the
Current configuration box contains the current settings for the ordering node.Not all of these values can be overridden after
deployment. Again, you don't need to include the entire set of parameters from the Current configuration JSON , only paste the
parameters you want to override into the Configuration JSON box.
The following list of parameters can be updated:

{
"General": {
"Keepalive": {
"ServerMinInterval": "60s",
"ServerInterval": "7200s",
},
"Authentication": {
"TimeWindow": "15m"
}
},
"Debug": {
"BroadcastTraceDir": null,
"DeliverTraceDir": null
},
"Metrics": {
"Provider": "disabled",
"Statsd": {
"Network": "udp",
"Address": "127.0.0.1:8125",
"WriteInterval": "30s",
"Prefix": null
}
}
}
example, if you only needed to update the value for the ServerTimeout field you would paste this JSON into the Configuration
JSON box:
{
"General": {
"Keepalive": {
}
}
}
Note: The ability to update an ordering node configuration is not available for ordering nodes that have been imported
into the console.
Using certificates from an external CA with your peer or ordering service

Instead of using an IBM Blockchain Platform Certificate Authority as your peer or ordering service's CA, you can use certificates
from an external CA, one that is not hosted by IBM. To use an external CA, the CA needs to issue certificates in X.509 format.
You need to generate your private keys using the PKCS #8 standard. For a quick tutorial, see Using certificates from an external
Certificate Authority.
Before you begin

1. You need to gather the following certificate information and save it to individual files that can be uploaded to the console.
Note: The certificates inside the files can be in either PEM format or base64 encoded format.
Peer or ordering node identity certificate This is the signing certificate from your external CA that the peer or
ordering node will use. This certificate must contain the Organizational Unit (OU) attribute "peer" or "orderer"
depending on the type of node it is used for.
Peer or ordering node identity private key This is your private key corresponding to the signed certificate from your
third-party CA that this peer or ordering node will use.
Peer or ordering service TLS CA certificate This is the public signing certificate created by your external TLS CA
that will be used by this peer or ordering node. The certificate needs to contain the x.509 Subject alternative name

(SAN) for the peer or ordering nodes. If you are using the Fabric CA client to enroll the identity, you specify the SAN
by passing the --csr.hosts parameter on the enroll command. If the host name is not yet known, you can specify
a wild card with the domain name, for example: --csr.hosts '*.ibpv2-cluster.us-
south.containers.appdomain.cloud,127.0.0.1'.
Peer or ordering service TLS CA private key This is the private key corresponding to the signed certificate from
your TLS CA that will be used by this peer or ordering node for secure communications with other members on the
network.
CA root certificate (Optional) This is the root certificate of your external CA. You can also provide an intermediate
CA root certificate or both.
TLS CA root certificate (Optional) This is the root certificate of your external TLS CA. You must provide either a TLS
CA root certificate or an intermediate TLS CA certificate, you can also provide both.
Intermediate CA TLS certificate: (Optional) This is the TLS certificate if your TLS certificate is issued by an
intermediate TLS CA. Upload the intermediate TLS CA certificate. You must provide either a TLS CA root certificate
or an intermediate TLS CA certificate, you may also provide both.
Peer or ordering service admin identity certificate This is the signing certificate from your external CA that the
admin identity of this peer or ordering service will use. This certificate is also known as your peer or ordering service
admin identity key. This certificate must contain the OU attribute "admin".
Peer or ordering service admin identity private key This is the private key corresponding to the signed certificate
from your external CA that the admin identity of this peer or ordering service will use.
Peer or ordering service organization MSP definition You must manually generate this file by using instructions
that are provided in Manually building an MSP JSON file.
2. Import the generated peer or ordering service organization MSP definition file into the console, by clicking the
Organizations tab followed by Import MSP definition.
Now you have the choice of creating a peer or single-node ordering service node, or ,if you have a paid cluster, a five node
ordering service.

Replace:
Now the private key can be used by the console. If you plan to include it in an organization MSP file, it needs to be encoded in
base64 format.
Option 1: Create a new peer or single-node ordering service using certificates from an external CA
Note: You can skip to Option 2 if you want to create a new five node ordering service. The following instructions are only
for creating a peer or single-node ordering service with certificates from your external CA.
Now that you have gathered all the necessary certificates, you are ready to create a peer or ordering service that uses those
certificates. Follow these instructions to create the peer or single-node ordering service with certificates from an external CA.
1. On the Nodes tab, click Add peer or Add ordering service.

2. Make sure the option to Create the peer or ordering service is selected. Then clickNext.
3. After you enter a display name for the node, select the option to use an external CA.
4. Step through the panels and upload the files corresponding to the certificate and private key you gathered.
5. Ensure you select the peer or ordering service organization MSP definition that you imported into the console from the

drop-down list.
6. On the last step when you are asked to associate an identity with your peer or ordering service, you need to clickNew
identity.
7. Specify any value as the Display name for this identity. The display name will be visible in the Wallet after you create the
node.
8. In the Certificate field, upload the file that contains thePeer or ordering service admin identity certificate.
9. In the Private key field, upload the file that contains thePeer or ordering service admin identity private key.
10. Review the information on the Summary page and click Add peer or Add ordering service.
11. After you have created the peer or ordering node, you can upload the orderer admin identity to the IBM Blockchain
console. On the Wallet tab, click Add identity:
In the Name field, enter an identity name that is used for your reference only.
In the Certificate field, upload a file that contains the admin identity's signing certificate (in base64 or PEM format).
In the Private Key field, upload a file that contains the admin identity's private key (in base64 or PEM format).
After you upload the certificate and private key of the identity to the console, you can use the console associate the identity
with the peer or ordering node.
Option 2: Create a five node ordering service using certificates from an external CA
When you have a paid Kubernetes cluster on IBM Cloud, you have the additional option of deploying a five node ordering service
that uses the Raft consensus protocol. Before you deploy a five node ordering service, you need to build a JSON file that
contains all of the certificates for the five nodes by using the following instructions:
Create the certificates JSON file

The required certificates JSON file contains an array of five msp entries, where each array element contains the certificates for
one of the ordering nodes. You must specify unique certificates for each node. Do not reuse certificates across the different
ordering nodes. The certificates in the component section represent the certificates for the node itself, while the tls section
includes the certificates issued by the TLS CA.
keystore: The private key for this node

signcerts: The public key (also known as a signing certificate or enrollment certificate) assigned by the CA for this node.
cacerts: The certificate of the root CA.
admincerts: The certificate of the admin users of the node. This might also be the admin of the organization.
intermediatecerts: If your network includes multi-level CAs, paste in the certificate of the intermediate CA. If you did not
use an intermediate certificate, you can leave this field blank.
Using the certificates that you gathered above, paste in the corresponding certificate in the fields below, in base64 format.
You can convert the contents of your certificate file, <cert.pem> from PEM format into a base64 string by running the following
command on your local machine:
export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-d"; else echo "-b 0"; fi)
[
{
"msp": {
"component": {
"keystore": “<cert>“,
"signcerts": “<cert>“,
"cacerts": [“<cert>“],
"admincerts": [“<cert>“],
"intermediatecerts": [“<cert>“]
},
"tls": {

}
}
},
{
"msp": {
"component": {
},
"tls": {
}
}
},
{
"msp": {
"component": {
},
"tls": {
}
}
},
{
"msp": {
"component": {
},
"tls": {
}
}
},
{
"msp": {
"component": {
},
"tls": {

}
}
}
]
Save this definition as a JSON file.
Create the ordering service and use the certificates from the external CA for each ordering node
After you create the JSON file with all of the certificates for the ordering nodes, you are ready to create the ordering service.
1. On the Nodes tab, click Add ordering service.

2. Make sure the option to Create an ordering service is selected. Then click Next.
3. Enter a single Display name for the five ordering nodes. The display name that you provide will be the prefix for each
ordering node name and a number will be appended to it.
4. In Number of ordering nodes, select Five ordering nodes. Then select External Certificate Authority configuration and
click Next.
5. Click Add file to upload the JSON file that contains all of the certificates.
6. Select the Organization MSP definition that you imported.
7. Because you are using a paid cluster, on the next panel, you have the opportunity to configure resource allocation for the
nodes. The selections that you make here are applied to all five ordering nodes. If you want to learn more about how to
allocate resources to your node, see this topic on Allocating resources.
8. Review the summary and click Add ordering service.
9. After you have created the ordering service, you can upload the orderer admin identity to the IBM Blockchain console. On
the Wallet tab, click Add identity:
In the Name field, enter an identity name that is used for your reference only.
In the Certificate field, upload a file that contains the admin identity's signing certificate (in base64 or PEM format).
In the Private Key field, upload a file that contains the admin identity's private key (in base64 or PEM format).
After you upload the certificate and private key of the identity to the console, you can use the console associate the
identity with your ordering node.
What's next
You have gathered all of your peer or ordering service certificates from your third-party CA, created their corresponding
organization MSP definition and created a peer or ordering service. If you are following along in the tutorials, you can return to
the next step.
If you created the peer node, the next step is to Create the node that orders transactions.
If you created the node to join an existing network, the next step is to Add your organization to list of organizations that
can transact.
If you created an ordering service, the next step is to Create a channel.
Configuring a node to use a Hardware Security Module (HSM)

Key management is a critical aspect of managing a blockchain network. Because private keys are not stored by the platform,
users are responsible for downloading and securing the private key of their node identities. In a production network, when a
higher level of security is required for private keys, an HSM is an optional hardware appliance that performs cryptographic
operations and provides the capability to ensure that the private keys never leave the HSM. Currently, Hyperledger Fabric
supports HSM devices that implement the PKCS #11 standard. PKCS #11 is a cryptographic standard for secure operations,
generation, and storage of keys.

Note: The ability to configure a node to use HSM is available only in paid clusters.
What capability does HSM add to my blockchain node?

When a CA, peer, or ordering node is configured to use an HSM, their private key is generated by and protected inside the HSM.
Only the private keys of node identities are secured in the HSM. When a CA is configured to use HSM, the CA root private key is
stored in the HSM. This is the key that is used to sign enrollment requests. After a peer or ordering node is configured to use
HSM, the nodes are able to sign and endorse transactions without ever exposing their private key. It is important to understand
though that when you register other node admin or client application identities with a CA by using the console, their private keys
are not stored inside the HSM because they will need their private key to transact on the network.
Considerations when using HSM

When you configure your HSM, you will create a partition and a PIN for the slot on the HSM.
A single partition can be used to generate and store multiple keys.
Multiple blockchain nodes can share an HSM configuration, however it is recommended that one HSM is configured per
organization.
An HSM is not configured for an ordering service. Rather it is configured at the ordering node level inside the ordering
service. Consider the case when different organizations contribute ordering nodes to an ordering service, it is possible that
some organizations may want to use an HSM for the private key for their ordering node, while other organizations may not
have that requirement. But all of the ordering nodes can still function together in the ordering service nonetheless.
The use of an HSM introduces an increase in transaction processing, therefore you can expect a performance hit when
using an HSM to manage the private keys for your nodes.
An HSM can be configured for a node only when the node is initially deployed. You cannot add HSM capability to existing
nodes at this time.
Configuring a node to use HSM is a three-part process:
1. Deploy an HSM. Utilize the HSM appliance that is available in IBM Cloud or configure your own HSM. Record the value of
the HSM partition and PIN to be used in the subsequent steps.
If you plan to use IBM Cloud HSM see this tutorial for an example of how to configure IBM Cloud HSM 6.0 with the
IBM Blockchain Platform. After that is completed you can skip to Part 3 Configure the node to use HSM.
2. Configure an HSM client image See Build a Docker image.
3. Configure the node to use HSM. From the APIs or the console, when you deploy a peer, CA, or ordering node, you can
select the advanced option to use an HSM. See Configure the node to use the HSM.
Before you begin

The Kubernetes CLI is required to configure the HSM. If you are using a Kubernetes cluster on IBM Cloud see Getting
started with IBM Cloud CLI or Installing the OpenShift CLI.
You need access to a container registry, such as Docker or the IBM Cloud Container Registry.
Build a Docker image

Configure HSM on your blockchain network by publishing an HSM client image to a container registry, as described below.
operator.



Chrystoki2 settings
files.

Chrystoki2 = {
}
...
LunaSA Client = {
...
...
}

file.

COPY 64 64

gcc \
gcc-c++ \
openssh-clients \
bind-utils \
iputils \
&& cd 64 && \

### Final image ###


look similar to:



<NAMESPACE>
Replace:



$ apiVersion: v1
data:
Chrystoki.conf: ""
cafile.pem: ""
cert.pem: ""
key.pem: ""
kind: Secret
metadata:
name: hsmcrypto

version: v1
type: hsm
resources:
limits: {}
requests: {}
securityContext:
privileged: false
runAsNonRoot: false
runAsUser: 0
library:
auth:
envs:
mountpaths:
paths:
- key: <KEY>
path: <PATH>

- key: <KEY>
path: <PATH>
paths:
- key: <KEY>
path: <PATH>
- key: <KEY>
path: <PATH>
them individually.
version: v1
type: hsm
library:
auth:
mountpaths:
- mountpath: /hsm
name: hsmcrypto
paths:
- key: cafile.pem
path: cafile.pem
- key: cert.pem
path: cert.pem
- key: key.pem
path: key.pem
- key: server.pem
path: server.pem
secret: hsmcrypto
name: hsmconfig
secret: hsmcrypto

/hsm/cafile.pem .
Configuring a CA, peer, or ordering node to use the HSM

Before attempting these steps you should have:
Deployed an HSM for your cluster.

Created a partition and PIN for the slot.
Deployed the HSM client image or the HSM proxy for your organization.
that takes approximately 0.1CPU and 100Mi memory.
Then you are ready to deploy a new CA, peer, or ordering node that uses the HSM.
When you deploy a new node from the console, ensure that you select the advanced deployment optionHardware security
module (HSM). This option is only available on paid clusters.
If you published an HSM client image and created the HSM configmap, theUse HSM client image toggle is visible. When it is on,
you can enter the following values:
If you did not create the HSM configmap, an additional field is required:
HSM proxy endpoint -Enter the URL for the endpoint.
Lastly, on the CA Summary panel, you can override the default HSM configuration, for example if you want to customize which
crypto library implementation to use. Click Edit configuration JSON (Advanced) on the Summary panel to view the JSON . Scroll
down to the BCCSP (Blockchain Crypto Service Provider) section where you can modify the crypto library settings.
Advanced channel deployment and management

When you create a channel, there are a number of advanced options that allow you fine tune the configuration of your channel to
fit your use case. In this topic we'll discuss how to edit those options as part of creating a channel or when editing a channel after
it has been created.

Target audience: This topic is designed for network operators who are responsible for creating, monitoring, and managing
channels.
Tip: The roles played by the various participants in channel creation, as well as the underlying method used to create and
update the channel configuration, is inherited from the Hyperledger Fabric processes for creating and editing a channel.
The parameters that govern how channels function, from the organizations on the channel to their permissions to the policies,
are all contained in the channel configuration. When you create a channel, you are asked to decide on a number of these
parameters. Some options, such as the channel name, cannot be changed after a channel has been created, while other options
can only be changed after the channel has been created.
General options
For an overview of the channel creation process that ignores the advanced options, see Step four: Create a channel.
Channel name. Channels should be given distinctive names relevant to the purpose of the channel. Each ordering service
can only have a single channel with a given name. If you see an error that a name has already been given to a channel on
that ordering service, you will have to select a new name.
Ordering service. Channels are hosted on a single ordering service and cannot be migrated from one ordering service to
another.
Organizations. This section of the panel is how organizations are added or removed from a channel. Organizations that
can be added can be seen in the drop-down list. Note that an organization must be a member of the consortium of the
ordering service before it can be added to a channel. For more information about how to add an organization to the
consortium, see Add your organization to list of organizations that can transact.
You can also update an organization's level of permission on the channel:
A channel operator has permission to create and sign channel configuration updates. There must be at least one operator
in each a channel.
A channel writer can update the ledger by invoking a smart contract. A channel writer can also instantiate a smart
contract on a channel.
A channel reader can only query the ledger, by invoking a read only function in smart contract for example.
Update policy. The update policy of a channel specifies how many organizations (out of the total number of operators in
the channel), who must approve of an update to the channel configuration. To ensure a good balance between
collaborative administration and efficient processing of channel configuration updates, consider setting this policy to a
majority of admins. For example, if there are five admins in a channel, choose 3 out of 5 .
Advanced options
By clicking the box under advanced options, users can access parameters that users should take caution in updating. Note that if
you are attempting to change any parameter that requires the signature of ordering service admins (for example, the Block
cutting parameters or ordering service consenters) and are one of the ordering service admins on this channel, you will see a
field for the ordering service organization. Select the MSP of the relevant ordering service organization from the drop-down list (if
you are not an ordering service admin, the MSP will have to be exported to you). If you are not an admin of the ordering service
organization, you can still make a request to change one of the block cutting parameters, but the request must be signed by an
ordering service admin.
Tip: If the signature of an ordering service org admin is required, you will not see a pending tile for the channel in your

console until the ordering service org has signed the request. When you see the tile, you can join your peer to it.
Capabilities. If you're unfamiliar with capabilities, check out Channel capabilities in the Fabric documentation. Note that
there is a strict relationship between the Fabric version of your nodes and the levels of certain capabilities that must be
followed to ensure that nodes do not crash and desired functionalities are available. Currently, only application and
orderer capabilities can be set during channel creation. For information about channel capabilities (which are a level of
capabilities that span both ordering nodes and peers and do not refer to "capabilities on the channel") and how to change
them, check out the Capabilities section below.
Lifecycle endorsement policy. (Only available on networks using v2.0 application capabilities) This defines how many
channel members must approve a smart contract definition before the smart contract can be used on the channel. This is
different from the endorsement policy of the smart contract itself as it has nothing to do with the transactions invoke
against the smart contract. Rather, the lifecycle endorsement policy is the criteria by which the organizations on the
channel collaboratively decide to use a particular smart contract and agree on certain parameters. It is possible to make
the lifecycle endorsement policy ALL (which means every channel member must approve the definition), ANY (which
means any channel member can approve the definition), or to define a specific set of organizations. Note that if you don't
specify a lifecycle endorsement policy, it defaults to MAJORITY, which means that a majority of Admins on the channel
will have to approve smart contract definitions. For more information about smart contract lifecycle endorsement, see
Deploy a smart contract using Fabric v2.x.
Smart contract endorsement policy. (Only available on networks using v2.0 capabilities) If a smart contract definition
does not define an endorsement policy for its transactions, the endorsement policy defined here will become the
endorsement policy of the smart contract. By default this policy is MAJORITY, which means a majority of endorsing
organizations will have to approve transactions that are invoked against this smart contract. However, as with the lifecycle
endorsement policy, it is possible to make the endorsement policy ALL, ANY, or to define a specific set of organizations.
For more information about default endorsement policies, see Install and propose a smart contract.
Block cutting parameters. These fields determine the conditions under which the ordering service cuts a new block. For
information on how these fields affect when blocks are cut, see the Block cutting parameters section below. Note that
changing these parameters will require the signature of an ordering service admin. If you are an ordering service admin,
you can sign this update using the Ordering service organization panel.
Ordering administrator (only available when updating a channel). This section shows the ordering service administrator
organizations for this channel.
Ordering cluster with a system channel - By default, all ordering organizations that are administrators are added to
an application channel at channel creation time. If an ordering service organization was added as an administrator of
the system channel after this application channel was created, it must be added to the channel before any nodes
belonging to it can be added as application channel consenters. Note: if your console is at a build before 2.1.3-104 ,
you will not see this option. To see the version of your build, click on the support icon in the upper right corner (it
resembles a question mark). The version will be listed below IBM Blockchain Platform version on the upper left.
Ordering cluster without a system channel - Ordering organizations that are administrators were added to the
application channel at channel creation. If an ordering service organization was created and intended to be an
administrator after the application channel was created, it must be added to the channel before any nodes
belonging to it can be added as application channel consenters.
Consenter set. The ordering service nodes on a particular channel are known in a Raft consensus mechanism as a
"consenter set". For this reason, the ordering nodes in a consenter set are sometimes referred to as "consenters". The
orderer's system channel (when applicable) will always contain all of the possible consenters available in a network (its
consenter set is "all consenters"), while application channels might have all consenters or some subset of consenters. It is
possible to add or remove particular nodes from this consenter set during both the creation of an application channel and
through a channel update. For example to add newly created orderers, if a system channel is being used they are first
added to the system channel, then to the consenter set of an application channel. To add a node to the consenter set, first

ensure that the organization that owns the consenter is an admin of the ordering service of the application channel
through the Ordering service administrator panel. You can then add the consenter through this Consenter set panel by
opening the drop-down list, clicking on a node, and clicking Add. For information about creating a new ordering node and
adding it to a consenter set, see the Adding and removing ordering service nodes tutorial. If you modify the consenter set,
you also have the ability to change the size of the ordering service Snapshot. For more information about Snapshots, see
Snapshots in the Fabric documentation.
Ordering service signature. If changes to the configuration are made that require the signature of an ordering service org
admin (for example, to the block cutting parameters, orderer capability, or consenter set), this panel will allow you to send
the change to the relevant ordering service admin organization. The console where the ordering service organization MSP
was created will see a signature notification. After the ordering service organization signs the channel update request, it is
sent back to the organization that requested the channel update to be submitted.
Access control lists (ACLs). To specify a finer grained control over resources, you can restrict access to a resource to an
organization and a role within that organization. For example, setting access to the resource ChaincodeExists to
Application/Admins would mean that only the admin of an application would be able to access the ChaincodeExists
resource. Users have the option to edit the access control list one at a time or by uploading a JSON containing the list. For
more information about Access Control, see Access Control Lists (ACLs) in the Fabric documentation.
Important: If you restrict access to a resource to a particular organization, be aware that only that organization will be
able to access the resource. If you want other organizations to be able to access the resource, you will have to add
them one by one. As a result, consider your access control decisions carefully. Restricting access to certain
resources in certain ways can have a highly negative effect on how your channel functions.
Updating a channel configuration

While creating a channel and updating a channel have the same goal, giving users the ability to ensure that the configuration of
their channel is as well suited as possible to their use case, the two processes are in fact very different as tasks in the console.
Creating a channel is a process undertaken by a single organization. As long as an organization is a member of the consortium of
the ordering service, they can create the channel in any way they want. They can give it any name, add any organizations (as long
as they are a member of the consortium), assign those organizations permissions, set access control lists, and so on.
The other organizations have the choice of whether to participate in this channel (for example, whether to join peers to it), but it
is assumed that the collaborative process of deciding on the channel configuration will happen out of band, before an
organization creates the channel.
Updating a channel is different. Rather than an organization acting alone, channel updates follow the collaborative governance
procedures that are fundamental to the way the IBM Blockchain Platform functions. This collaborative process involves sending
the channel configuration update requests to operator organizations that have an administrative role in the channel.
Because selecting Anchor peers and Joining a peer to a channel are actions that only require the signature of the organization
performing the action, they are updated through the Channel details panel inside a channel. To update other parameters, you
must click on the Settings button next to the channel name at the top of the page and initiate a channel configuration update
transaction. A panel will appear that looks very similar to the panel you use to create a channel.
Signature collection flow
Important: For signatures to be verified, all of the organizations on a channel (including the ordering service
organizations) should export the MSPs representing their organizations to the other organizations on the channel. To
export an MSP, click the download button on your MSP (on the Organizations tab), then send it to other organizations out

of band. When you receive an MSP JSON file, import it using the Organizations panel. For more information about
exporting and importing, including information about to export and import in bulk, see Importing nodes.
Whenever a channel request is made that requires signatures (whether it is during channel creation, as when an ordering service
admin signature is required, or during a channel update, when channel operators will likely need to sign), it will be sent to the
organizations in the channel whose signatures are required. For example, if there are five operators (channel admins) in a
channel, an update request will be sent to all five. For the channel request to be approved, the number of channel operators
listed in the channel update policy must be satisfied. If this policy says 3 out of 5 , the new channel configuration update will
take effect after three organizations have signed it and it has been submitted.
This process of knowing when you have an update to sign, as well as signing it, is handled through theNotifications button
(which looks like a bell) in the top right of the console. When you see a blue dot on the Notifications button, it means that you
either have a pending request to evaluate or are being notified of a channel-related event.
When you click on the Notifications button, you may have one or more actions you have the ability to take:
Needs attention: a request needs to be signed or submitted (if all required signature have already been collected). The
request might be to either your peers or ordering service, depending on the organizations in your console.
Open: includes everything that needs attention as well as requests that have been signed by the user but still need to be
signed by one or more other channel members.
Closed: requests that have been submitted. No actions to be taken on these items. They can only be viewed.
All: includes both open and closed requests.
If a channel configuration update request has been made, you have the ability to click onReview and update channel
configuration and see the changes to the channel configuration update that are being proposed or have been made (if the new
channel configuration has been approved). If you are an operator on the channel, and not enough signatures have been gathered
to approve the channel configuration update request, you will have the ability to sign the update request.
Note: You are not required to sign a channel configuration update, however note that there is no way to signagainst a
channel update. If you do not approve of a channel configuration update, you can simply close the panel and reach out to
other channel operators out of band to voice your concerns. However, if enough operators in the channel approve of the
update to satisfy the channel update policy, the new configuration will take effect.
Channel configuration parameters you can update

It's possible to change many, but not all, of the configuration parameters of a channel after the channel has been created. The
Channel name, for example, cannot be edited, nor can the ordering service where the channel is hosted.
First thing you will see is the Organization updating channel panel. Here you will specify the organization (MSP) and admin
identity that will be submitting this channel configuration update. From here, you can navigate down to the parameter you want
to change, which includes all of the same parameters you specified when creating the channel other than the channel
capabilities and the ordering service administrator, which are only available when updating a channel.
Tip: If your console is at a build before 2.1.3-104 , you will not see the ordering service administrator option. To see
the version of your build, click on the support icon in the upper right corner (it resembles a question mark). The version will
be listed below IBM Blockchain Platform version on the upper left.
If you are attempting to change any parameter that requires the signature of ordering service admins (for example, theBlock
cutting parameters or ordering service consenters) and are one of the ordering service admins on this channel, you will see a
field for the ordering service organization. Select the MSP of the relevant ordering service organization from the drop-down list. If
you are not an admin of the ordering service organization, you can still make a request to change these fields, but the request

must be signed by an ordering service admin.
When you are done making your updates, the Review channel information panel will allow you to review your changes and then
submit them.
Anchor peers
Because cross organizational gossip must be enabled for service discovery and private data to work, each organization should
specify at least one anchor peer on each channel. This anchor peer is not a special type of peer. It is just the peer that
bootstraps cross organizational gossip.
Note that while anchor peers are a channel configuration parameter, they are not set through the normal process of creating and
editing a channel configuration.
To configure a peer to be an anchor peer, click theChannels tab and open the channel where the smart contract was deployed.
Click the Channel details tab.

Scroll down to the Anchor peers table and click Add anchor peer.
Select at least one peer from each organization in collection definition that you want to serve as the anchor peer for the
organization. For redundancy reasons, you can consider selecting more than one peer from each organization in the
collection.
Join a peer to a channel

The ordering service and the peers known to this console that are joined to this channel are listed in theNodes field at the top of
the channel page. It is possible to add peers to this channel by clicking the Join peer button. On the panel that opens, you can
specify the peers you want to join this channel, as well as whether you want this peer to bootstrap gossip communication
between your organization and other organizations by making this peer an anchor peer. If you already have specified an anchor
peer for this channel, you do not need to make this peer an anchor peer (only one anchor peer is needed to bootstrap
communication between organizations), though it is sensible to make anchor peers HA by making sure you have at least two
anchor peers in each channel.
As with the process for joining any peer to any channel, make sure that the database type of this peer is compatible with the
database type of the channel. Similarly, ensure that the Fabric level of this peer is at the application and channel capability
levels of the channel.
Note that after a peer is removed from a channel, it might still show as being joined to the channel. This is because the ledger
information of the channel up to the point the peer was removed is still available on the peer. Removing the peer from the
channel means that the peer will receive no new channel updates, including the update that indicates that it is no longer a part
of the channel. If you have any other peers joined to the channel, you can check the ledger height of those peers as compared to
the peer that was removed to confirm that the removed peer is not receiving new blocks.
Capabilities
Tip: For a thorough look at what capabilities are how they work, check out Channel capabilities.
The capability levels of a channel and the Fabric versions in the nodes on that channel must be coordinated in order for nodes
and channels to function properly. That is because both nodes and capabilities work together to ensure that transactions are
handled deterministically (that is, that all of the nodes process a transaction the same way). While the Fabric versions of a node
are compatible with lower levels of capabilities, capabilities cannot be processed by lower levels of nodes. If a v1.4.x node
attempts to read a configuration block containing a v2.x capability, the node will crash. For this reason, the console will attempt
to ascertain the nodes that will be affected by a capability update and either warn you (or stop you) from updating a capability if
it will cause a node to crash. More on this later.

Because of this, all of the nodes in a channel must be at least at the level of the capabilities relevant to the node. Therefore, if
the organizations in your channel want to "move to v2.0", this is in practice a three step process:
1. Upgrade all of the nodes in the channel. For more information, check out Upgrading to a new version of Fabric.
2. Update the relevant capabilities of the channel. Do not attempt to edit the capabilities until you are sure your nodes are at
the appropriate Fabric versions.
3. To use the 2.x smart contract lifecycle, an organization must have an endorsement policy defined. If any organization in
the consortium (the list of organizations maintained by the ordering service that are allowed to create channels) do not
have an endorsement policy defined, a warning message will appear on the Details page of the ordering service with a list
of organization MSPs that must be updated. The best practice to add this endorsement policy to the MSP is to delete the
MSP from the system channel and then re-add the MSP. The console detects the fact that the MSP does not contain the
endorsement policy and automatically adds it. Note that this action can only be completed by an ordering service
administrator. You do not need to delete and re-add the MSPs in the configuration of any application channels that have
already been created. For these MSPs, the endorsement policy is added as part of the process of deploying the smart
contract using the v2.x lifecycle.
Tip: The application and channel capabilities are relevant to peers, while the orderer and channel capabilities
are relevant to the ordering service.
While all capabilities can be edited as part of a channel configuration update request, you have the opportunity to edit these
capabilities in a few places:
Channel and orderer: in the system channel by ordering service admins.

Application and orderer: during channel creation.
Note that what you see in this section will depend on the configuration of your channel and the Fabric level of your peers and
ordering nodes, as only valid and possible capability upgrades will appear. For example, if your channel, orderer, and
application capabilities are already at the highest level, you will only see the capability levels that have been selected. Similarly,
you will not see potential capability updates if your nodes in the channel are not at a sufficient Fabric level to process the
capability. Note that in orderers that use a system channel the default orderer capability shown is inherited from the system
channel. Orderers that do not use a system channel will default to using v2_0 capabilities. While the default application
capability is set to a reasonable level that will ensure that peers who attempt to join the channel will not crash. The application
capability can always be updated later.
Important: To ensure that you will always be able to see and propose updates to get a channel to the latest capability
levels, it is a best practice to upgrade your peers and ordering nodes to the latest Fabric version as soon as it is
available in the console. From a channel management perspective, it is also a best practice to discuss capability updates
with other organizations before proposing a change. This will allow organizations to update nodes, as necessary, before
the channel update request is submitted.
Capabilities in the system channel

Because the ordering service is involved in the validation of the orderer and channel capabilities, these capability levels exist
in the system channel (if applicable). By default, any channel that is created on an ordering cluster that uses a system channel
will inherit these capability levels. Because only the orderer capability (and not the channel capability) is apparent when
creating a channel, it is important to communicate the channel capability level to consortium members so they can ensure that
the level of their peers is at the Fabric version of the capability level or higher.
Tip: In order to edit the orderer or channel capabilities in the system channel, your organization must be an ordering
service administrator.
To edit these capabilities, click on the Settings button inside the ordering service. Then click Capabilities. Note that the channel

and orderer capabilities, as well as the application capabilities, can also be edited through a channel configuration update.
However, an ordering service admin will have to sign any configuration update that edits the orderer or channel capabilities.
Note that capability versions can only advance. You cannot go back to a previous capability or downgrade from a default
capability level to a lower version.
Important: It is not possible to update the orderer or channel capabilities to a level that will crash your ordering
nodes. If you want to update your capabilities on the system channel screen, you must first upgrade your nodes.
Capabilities in application channels

Application capabilities define the way transactions are handled exclusively by the peers. As a result, these capabilities are not
inherited from the system channel (which is managed by the ordering service) and the full list of capabilities can be seen,
starting with 1.1 , when creating a channel. Note that the Fabric version of all peers in the channel must be at least at the level
of the application capability level and the channel capability level inherited from the ordering service. When creating a channel,
the default application capability might be lower than the highest available level. This is done in cases where a new Fabric
version with a new application capability has been released but it is not expected that most peers will be at the new Fabric
version. You will see the default application capability in the Review channel information screen before creating the channel.
If you attempt create a channel with a orderer capability other than the default, the channel creation request must be signed
by an ordering service organization. If this capability is incompatible with the Fabric version of your ordering nodes, the console
blocks the signature from completing, as a successful signature would crash any ordering nodes at the lower Fabric version. You
must upgrade all of the relevant nodes before the channel creation request can be signed.
Similarly, the console will block any attempt to join a peer to a channel with an application or channel capability it is
incompatible with to prevent the peer from crashing. The peer must be upgraded before it can be joined to the channel.
Because channel creation requests cannot be edited, if a capability is selected in error, a new channel creation request must be
made. {tip}
The following table shows the compatibility levels of peer image versions with the application capability level of a channel and
which smart contract deployment process is used:
Channel application capability 1.4 Channel application capability 2.x
Peer Uses legacy smart contract Not possible

image
1.4.x deployment flow and requires smart contract in .cds
file format.
Peer Uses legacy smart contract Uses Fabric 2.x smart contract
image
2.x deployment flow and requires smart contract in .cds lifecycle and requires smart contract in .tgz file
file format. format.
Table 1. Peer image version vs. channel application capability level
A peer that runs a Fabric 1.4.x image can join a channel that is configured with application capability 1.4.x. But that peer
cannot join a channel that is configured with application capability 2.x.
If a channel application capability level is upgraded to 2.x before the peer 1.4.x image is upgraded to 2.x, the peer stops
functioning and needs to be upgraded to the 2.x image.
It is possible for a peer that is running a 2.x image to join a channel with application capability 1.4 and another channel
with application capability 2.x at the same time. But smart contracts on the peer in .cds format use the legacy smart
contract deployment process where they have to be instantiated on the channel withapplication capability 1.4. Smart
contracts on the peer in tar.gz format follow the Fabric 2.x smart contract lifecycle process on the channel with
application capability 2.x.
Like the orderer and channel capabilities, the application capability level can be edited through a channel configuration update.

The orderer capability can also be specified during the creation of a channel, but will require the approval of the ordering service.
Important: If you are using the SDK to create or edit a channel, take caution to not submit a channel configuration with
an invalid application capability. Because application capabilities are not validated by the ordering service, invalid
application capabilities are not flagged. Because the peers cannot process capabilities that do not exist, the peers will
crash when attempting to read the configuration block containing an invalid capability. Because the peers will be unable to
progress beyond this configuration block, it will not be possible to reverse this configuration block and submit another one
to "fix" the problem. A channel in this state is unrepairable.
Tuning your ordering service

Performance of a blockchain platform can be affected by many variables such as transaction size, block size, network size, as
well as limits of the hardware. The orderer node includes a set of tuning parameters that together can be used to control orderer
throughput and performance. You can use these parameters to customize how your orderer processes transactions depending
on whether you have many small frequent transactions, or fewer but large transactions that arrive less frequently. Essentially,
you have the control to decide when the blocks are cut based on your transaction size, quantity, and arrival rate.
The following parameters are available in the console by clicking the orderer node in theNodes tab and then clicking its Settings
icon. Click the Advanced button to open the Advanced channel configuration for the orderer.
Block cutting parameters

The following three parameters work together to control when a block is cut, based on a combination of setting the maximum
number of transactions in a block as well as the block size itself.
Absolute max bytes Set this value to the largest block size in bytes that can be cut by the orderer. No transaction may be
larger than the value of Absolute max bytes . Usually, this setting can safely be two to ten times larger than your
Preferred max bytes . Note: The maximum size permitted is 99MB.
Max message count Set this value to the maximum number of transactions that can be included in a single block.
Preferred max bytes Set this value to the ideal block size in bytes, but it must be less thanAbsolute max bytes . A
minimum transaction size, one that contains no endorsements, is around 1KB. If you add 1KB per required endorsement,
a typical transaction size is approximately 3-4KB. Therefore, it is recommended to set the value of Preferred max bytes
to be around Max message count * expected averaged tx size . At run time, whenever possible, blocks will not
exceed this size. If a transaction arrives that causes the block to exceed this size, the block is cut and a new block is
created for that transaction. But if a transaction arrives that exceeds this value without exceeding the Absolute max
bytes, the transaction will be included. If a block arrives that is larger thanPreferred max bytes , then it will only
contain a single transaction, and that transaction size can be no larger than Absolute max bytes .
Together, these parameters can be configured to optimize throughput of your orderer.
Batch timeout
Set the Timeout value to the amount of time, in seconds, to wait after the first transaction arrives before cutting the block. If you
set this value too low, you risk preventing the batches from filling to your preferred size. Setting this value too high can cause the
orderer to wait for blocks and overall performance to degrade. In general, we recommend that you set the value of Batch
timeout to be at least max message count / maximum transactions per second .
Important: When you modify these parameters, you do not affect the behavior of existing channels on the orderer; rather,
any changes you make to the orderer configuration apply only to new channels you create on this orderer.
Other performance considerations

In addition to the previous topics, the following considerations can help optimize your network performance:

Ensure persistent storage IOPS is not a bottleneck. Persistent storage IO requests can become a bottleneck in some
solutions. 10 IOPS/GB+ is recommended.
Performance generally scales with CPU allocated to peer nodes. Providing each peer and CouchDB (if used) with the
maximum CPU capacity is recommended.
Use Fabric 2.x so chaincode runs as a separate process.
Increasing the ordering node sendBufferSize default of 10 can improve ordering service performance (100 is the
recommended starting point).
Check CouchDB logs for warnings such as "The number of documents examined is high in proportion to the number of
results returned. Consider adding a more specific index to improve this." Indexes for CouchDB rich queries are essential
for performance, and will indicate when too many documents are being scanned (full table scans) for a relatively low
number of results.
For ordering service nodes, use monitoring to determine load and CPU pressure. Generally, 1 CPU/2GB RAM prevents
ordering service nodes from becoming a bottleneck.
Adding and removing ordering service nodes

In this tutorial, we'll talk about the process for creating ordering nodes to add to an existing ordering service and to existing
channels. This will cover the instructions for adding nodes using the same organization that created the ordering service as well
as the steps when using a separate ordering organization that is added as an ordering service admin.
Important: Because ordering nodes that use a system channel can only belong to a single ordering service, if you create
an ordering service node from the main Nodes panel, you will not be able to add it to an existing ordering service. If you
want to add a node to an existing ordering service, the node must be created specifically for that purpose using the
process described below. Also, be aware that adding nodes to an ordering service does not automatically add them to
any existing channel. That is a separate process that must take place after the node has been added to the ordering
service. For more information, see Adding and removing ordering service consenters.

While it's technically possible to build a configuration of any number of ordering nodes (no configuration is explicitly restricted),
some numbers provide a better balance between cost and performance than others. The reason for this lies in satisfying the
needs of high availability (HA) and in understanding the Raft concept of the "quorum", the minimum number of nodes that must
be available (out of the total number) for the ordering service to process transactions.
In Raft, a majority of the total number of nodes is needed to form a quorum. In other words, if you have one node, you need
that node available to have a quorum, because the majority of one is one. Similarly, if you have two nodes, you will need both
available, since the majority of two is two (for this reason, a configuration of two nodes is discouraged; there is no advantage to a
two node configuration). In a similar vein, the majority of three is two, the majority of four is three, the majority of five is three,
and so on.
While satisfying the quorum will make sure the ordering service is functioning, production networks also have to think about
deployment configurations that are highly available (in other words, configurations in which the loss of a certain number of
nodes can be tolerated by the system). Typically, this means tolerating two nodes failing: one node going down during a normal
maintenance cycle, and another going down for any other reason (such as a power outage or error).
This is why, by default, the console offers two options: one node or five nodes. Recall that the majority of five is three. This
means that in a five node configuration, the loss of two nodes can be tolerated. If your configuration features four nodes, only
one node can be down for any reason before another node going down means a quorum has been lost and the ordering service
will stop processing transactions.
For this reason, it is considered a best practice to have an odd number of nodes in an ordering service. There is nothing wrong
with an even number of nodes, but they add costs without making the ordering service more highly available.

Tip: Because the number of nodes needed for a quorum is updated automatically when nodes are added to the consenter
set, it is a best practice to make sure that all of the nodes in the consenter set are servicing the channel before attempting
to add a new node. This is because the consenter set is updated before the node has finished provisioning. For example, if
you have three nodes servicing a channel, you will have a quorum as long as two nodes are up. When attempting to add a
new node, the consenter set will index to three nodes being needed (out of four). In a case where only two nodes are up
out of three when a new node is added, and the new node fails to provision for any reason, you will only have two nodes
available out of the three that are needed.
Overview
Adding a node to the ordering service is, at a high level, a three step process.
1. Create the node to be added to an existing ordering service.

2. Add the node to the ordering system channel (this step can be omitted on ordering clusters that do not use a system
channel). While this might seem logically similar to creating the node, it involves a different step. For more information,
see Adding the node to the ordering system channel.
3. Add the node to any application channels where you want it to become a consenter.
If you have already created an ordering service, you can reuse the CA, MSP, node identity, and admin identity you created as part
of that process when creating the new node and can skip down to the Create the node section below. If you are creating the
node using either a separate console and separate organization (or both), proceed to Create the node using a separate org and
console.
Create the CA and organization for the new node

If an organization other than the organization that created the ordering service wishes to create a new node, they will need to
complete several steps. For the purpose of this tutorial, it is assumed that a user has followed the Build a network tutorial in
their console and has created a peer, ordering service, and an application channel. Subsequent to this, a separate user, with a
separate console, wishes to add a node to that ordering service, which is called Ordering Service.
Important: As part of describing the process for creating a new node from a separate console, we will refer to "Console
1" and "Console 2". Console 1 is the originating console; it's where the ordering service was originally created. Console 2
is where a user is attempting to create a new node for this ordering service using a different organization in a different
console.
Unless you have already created new nodes for this ordering service, do not reuse an existing CA and MSP.
The process of creating a CA, registering identities, and creating an MSP is identical to the process described in Creating your
ordering service organization CA from the Build a network tutorial. However, use the following values:

Create CA Ordering Service2 CA admin adminpw
Register users Ordering Service2 admin OS2admin OS2adminpw admin
Ordering Service node identity OS2 OS2pw orderer
Table 1. Create a CA and register users

Tip: If you are using a separate console, it is possible to specify exactly the same values for these fields as was specified
in the Build a network tutorial. Only the mspid from the fields below must be different than osmsp , as two different MSPs
cannot have the same ID in the same console (the MSP you create here will be exported to the other console in a future
step). However, we have given different values in this tutorial in case users are running this tutorial inside the same
console.
After your CA has been created and your identities have been registered, create the MSP representing your organization and an
admin representing that organization using the following values:

Create Organization Ordering Service2 MSP os2msp
Root CA Ordering Service2 CA
Org Admin Cert OS2admin OS2adminpw
Identity Ordering Service2 MSP Admin
Console 2: export the Ordering Service2 MSP

Now that you have created the Ordering Service2 MSP , you need to export it to other members of the network (in this
tutorial, that means exporting it to the operator of Console 1). You should have downloaded a copy of your MSP to your local
machine during the creation process, but if you have not yet done so, download the MSP now. Then send the JSON to the
operator of the other console out of band.
Until your organization is an administrator of the ordering service, you cannot add a new node to it.
Figure 1. Export the MSP from Console 2

Console 1: import Ordering Service2 MSP and export Ordering Service
The operator of Console 1 must take the Ordering Service 2 MSP and add it to its console by clicking on theOrganizations
tab and then the Import MSP definition tab.
Figure 2. Import the MSP into Console 1
This MSP can then be added as an ordering service administrator by clicking on the tile representing the ordering service and
then the Add ordering service administrator tab and selecting Ordering Service 2 MSP from the drop-down list.
Figure 3. Make Ordering Service2 MSP an admin
Tip: While it is also possible to upload a JSON representing the MSP by clicking theUpload JSON tab, be aware that if you
do this, the MSP will not appear in the Organizations tab and will therefore not be selectable later (for example, when
updating an application channel to add the MSP as an ordering service administrator). For this reason, the best practice is
to import the MSP through the Organizations tab first.
After the MSP has been added as an ordering service administrator, the operator of Console 1 must export the ordering service
to Console 2. To export a node, navigate to the node and click on the "download" button (the button looks the same as it does in
the above image showing the download of Ordering Service2 MSP ). Then send the JSON file representing the ordering
service to the operator of Console 2.
Console 2: import Ordering Service

After the operator of Console 2 has the JSON representing Ordering Service on its file system, they must click Add ordering
service on the Nodes panel. Then, they must click Import an existing ordering service and click Next. On the following panel,
they can click Add file and select the ordering service. Note that importing and associating an admin identity for this ordering

service is an optional step. You can create a new node either way.
After Console 2 has imported the Ordering Service , they will be able to create the new node.
Figure 4. Import the ordering service
Create the node
Tip: While it is not possible to ensure that the ordering service is available (that is, that a quorum of nodes are up and that
a leader has been elected) without Viewing your node logs, it is a best practice to minimally ensure the likelihood that a
quorum exists by verifying that the pods where the nodes have been deployed are available. This can be done by checking
to make sure the relevant pods are active in the Kubernetes dashboard or by issuing kubectl get pods -n
<namespace> and checking on the pods. If you do not have access to the cluster where all of the ordering nodes were
created, contact the administrator of the relevant clusters. If a quorum of nodes is not available, it will not be possible
to add another node to the ordering service.
To add a node, click on the tile representing the ordering service in theNodes panel. Then click on the Ordering nodes panel
and the Add another node tile. Then click Create an ordering node. This will open a series of panels similar to the process for
creating an ordering service.

Figure 5. Add another node
You will need to:
Give the node a display name. A best practice will be to give the node a display name that matches the pattern used for
the other nodes in the ordering service. By default, nodes are given the name <name of ordering service>_1 , <name
of ordering service>_2, and so on.
Select a CA. This should be the CA used to create your MSP.
Enter an enroll ID and secret. Again, if you created an enroll ID and secret for your existing ordering nodes, you may use
the same enroll ID and secret here.
Select an MSP. If you are adding to an ordering service you created in your console, reuse the MSP you used when
creating that ordering service. If the new node is being added to an ordering service created elsewhere, use the MSP you
exported to that console.
Choose a Fabric version for the new node. Note that this must be the same Fabric version used by the other nodes in the
ordering service. If you choose a different Fabric version, the new node will be unable to join the consenter set.
Associate identity. You will only have to associate an identity if you are using a different MSP from the MSP that was
originally used when creating the ordering service.
Tip: The TLS Certificate Signing Request (CSR) hostname is an option available to advanced users who to want specify a
custom domain name that can be used to address the ordering service endpoint. Custom domain names are not a part of
this tutorial, so leave the TLS CSR hostname blank for now.
Display name MSP ID Enroll Secret Version

ID
Add another node Ordering Service_2
CA Ordering Service2 CA
Ordering Service OS2 OS2pw

Identity
Organization MSP Ordering Service2 MSP os2msp
Fabric version Version of nodes in existing

ordering service

Administrator Ordering Service2 MSP
certificate
Associate identity Ordering Service2 MSP

Admin
After reviewing the Summary page, click Add another node. This will submit the creation request.
To complete the process of adding the node, you need to add it to the consenter set of the system channel (if applicable). For
information about how to do that, proceed to the next section. Ordering clusters that do not use a system channel can skip to the
step Add Ordering Service2 MSP to channel1
Add the Ordering Service_2 node to the orderer system channel

Important: This step must be completed in the console that created the new node. If you followed the steps for creating
a node from a different console, this would be Console 2.
After the ordering node has been successfully added, a new tile with the name of the node will appear on theOrdering nodes
page. It will say it "Requires attention". This state reflects the fact that, while the node creation process has been successful, the
node is not yet part of the consenter set of the system channel. The node must be added to the system channel before it can be
added to any of the application channels.
Tip: Recall that the "consenter set" refers to the ordering service nodes actively participating in the ordering process on a
channel, while the "system channel", which is managed by the ordering service, forms the template for application
channels.
To add the node you created to the system channel, click on the node. You will see aAdd node to ordering service button. Click
this button. After the node has been added to the ordering service, the node should now be part of the system channel.
Note that it will take a few minutes for the new node to sync with ordering service in the system channel. During this time,
you may see a message that your ordering service is down. This is normal --- the ordering service must come down while the
new node is syncing. Any transactions proposed during this time will fail and will have to be resubmitted by the client
application.
If you created this new node and added it to the system channel from a different console (Console 2), you must then export it to
the console that originated the ordering service (Console 1). If the new node was added in Console 1, you can skip down to
Adding the node to the application channel.
Console 2: export the Ordering Service_2 node

After the Ordering Service_2 node has successfully been created and added to the system channel, Console 2 must export a
JSON representing the node to every channel member (in this tutorial, this means exporting it to Console 1). This will allow all
channel members to have an accurate record of the nodes in the ordering service (which will allow the node to be selected from
drop down lists, for example when adding consenters to channels).
To do this, click on the node and then on the "download" button. This will download a JSON representing the node to your
filesystem. This JSON can then be sent to other network members out of band.

Once the node has been exported to the consoles of other channel members, those members will be able to add the node as a
consenter to existing channels (where desired), and be able to accurately monitor the health of the ordering service.
Note that adding a new node to the system channel does not automatically add the node to any application channels.If you
want to add this node to any existing application channels, you will have to add them to the consenter set of each of those
channels separately. For information about how to do that, see Adding an ordering node to the consenter set of a channel.
Console 1: add the Ordering Service_2 node to your console
Important: This step should be completed by every channel member.
To do this, click on the tile representing the ordering service, which in this tutorial is called Ordering Service. Then click on
the Ordering nodes tab and then the Add another node tab.
Then click Import an existing node. After clicking Add file, find the JSON representing the Ordering Service_2 node that was
sent to you by the operator of Console 2. After you have added the Ordering Service_2 node, you should see it on the
Ordering nodes page.
Figure 6. Add the Ordering Service_2 node to your console
Update channel1 to add the Ordering Service2 MSP and the Ordering Service_2 node
Important: This step can be completed by any channel member.
Because this tutorial presumes that a user is adding a node to a channel that was created as part of theBuild a network tutorial,
the channel the Ordering Service_2 node is being added to, channel1 , does not yet have the newly created ordering service
organization, Ordering Service2 MSP , as one of the administrators of the channel. While a new ordering node can be added
to a channel even if the organization that owns the node is not an administrator of the ordering service, it is a best practice to add
the organization that owns the node when you add the node.
Because you are editing a part of the channel configuration that is governed by ordering service organization admins, you will be
asked to send the channel configuration update to an ordering service organization admin to be signed as part of the
configuration update process. This organization can be any of the organizations that is an admin of the ordering service, not
just one of the organizations that owns one of the consenters that is already in the channel. In this tutorial, that means selecting
Ordering Service MSP . Do not select Ordering Service2 MSP here as it is being added as part of this channel
configuration update.

Add Ordering Service2 MSP to channel1
To add an ordering service organization to an application channel, navigate to the channel and click theSettings button. First,
specify which peer organization and which peer organization admin is making the update request. If the application channel was
created before the ordering organization was added to the system channel, click Ordering service administrator and add
Ordering Service2 MSP as an administrator.
Important: If your console is at a build before 2.1.3-104 , you will not see this option. To see the version of your build,
click on the support icon in the upper right hand corner (it resembles a question mark). The version will be listed below
IBM Blockchain Platform version on the upper left.
After the organization has been added, we can add the consenter.
Tip: It is possible to add a node to the consenter and add the MSP of the organization that owns the node as part of the
same channel configuration update.
Add the node to the application channel

After adding the organization, click on the Consenter set tab, select the Ordering Service_2 node from the drop down list,
and click Add. Note that you will only be able to add one node to a channel at a time.
After the Ordering Service MSP has signed the channel configuration update, the organization that initiated the channel
update will get a notification that it must sign and submit the channel configuration update. This notification, like all notifications,
will be located in the upper right of the screen behind the Notifications icon, which resembles a bell. For more information about
how signature collections work, see Signature collection flow.
It will take a few minutes for the new node to sync with the consenter set of the application channel. The time involved
depends on a number of factors, including the number of blocks in a channel. During this time, the ordering service may be
down. After the node has been successfully added to the application channel, you will see it in the Ordering nodes tab.
Join the node to the application channel

Clusters that do not use a system channel can join and unjoin ordering nodes to an application channel. You can verify if a cluster
does or does not use a system channel by clicking the cluster's tile and looking near the Orderer Type text.
Joining an orderer to an application channel will make it either a follower or a consenter . It will be a consenter if the node is
found in the the channel's config block in the consenters section. Otherwise the orderer will be a follower . Both types of
orderers will receive transaction/block data, but only a consenter can vote and play a role in the consensus algorithm. A node
can be promoted from a follower to a consenter by first joining it to the channel, and then editing the channel's config to
add it as a consenter. Similarly these steps can be reversed to demote an orderer and unjoin it completely if need be.
Joining an orderer to the application channel can be started by clicking the cluster's tile. Next click either the plus sign on a
channel tile or the Join channel blue button. Follow the prompts and select which orderer nodes to join. Then click Submit .
Once an orderer has joined it will begin downloading blocks to catch up to the current level.
Removing ordering service nodes

If a user wants to delete an ordering node, it must first remove the node from all channels where it is a consenter. This is
because the console does not distinguish between a deleted node and an unavailable node, and will keep an ordering node as
part of its consenter set until it is removed.

As a result, when you delete a node, a check is performed to see if it is a consenter on any channels. If it is, you will not be able
to delete the node until it has been removed as a consenter from all channels. After removing the node as a consenter from all
channels, you will be able to delete the node by clicking the trash can icon. Note that this action will have to be taken in the
console where the node was created.
As part of this same process, make sure to reach out to the other console operators to let them know that the node has been
deleted so they can remove the tile from their console.
Important: Note: if you remove all of the ordering nodes that originally formed the consenter set of a channel, you might
have to create a mapping from the old ordering nodes to the new nodes by editing the configuration of any new peers you
attempt to join to the channel. For more information, see Mapping to existing ordering nodes.
Mapping to existing ordering nodes

When a peer attempts to join a channel, it first pulls the initial configuration block (known as the genesis block) that was created
when the channel was created. This block lists, among other things, the addresses of the ordering nodes that are consenters on
the channel. As long as one of these nodes is still alive, the peer can pull down the ledger associated with this channel from that
node and learn about any new ordering nodes that are now servicing the channel.
If none of the ordering nodes that were consenters on the channel are still up, any peer attempting to join the channel will try
and fail to connect to the nodes listed in the genesis block and be unable to proceed past that point.
In these cases, it is necessary to edit the configuration of the peer itself with a code snippet provided by the console. This code
snippet will point the peer to one of the ordering nodes servicing the channel and allow the ledger of the channel to be pulled
from that node.
Editing the peer configuration

If your channel is in the state described above, in which none of the original ordering nodes are still servicing the channel, when
attempting to join a peer to the channel the Join a peer to the channel screen will show a message similar to the following
advising you that the configuration of the peer must include an "orderer override":

Figure 7. Orderer override code snippet
When you see this screen, copy the code snippet. Note the addressOverrides section. It should contain the address of one of
the original ordering nodes as well as the address of one of the nodes now servicing the channel.
Then, paste the code snippet into the configuration of the peer. To do this:
1. Navigate to the peer from the Nodes panel.

2. Click on the Settings button inside the peer.
3. Under Actions, click on Edit configuration JSON (Advanced).
4. In the box under Configuration updates, paste the code snipped you copied on the Join a peer to the channel page.
5. When you're ready, click Update peer.
The peer will automatically restart. When it is back up, you should be able to join the channel.

Figure 8. Editing the peer configuration
Note that you may have to edit the configuration of a peer multiple times, depending on the status of the ordering nodes on
different channels. The override logic is designed to handle more than one "override" section in the peer configuration.
Important: Don't copy the configuration snippet used as an override for one peer and use it on any other peers. Similarly,
don't open the configuration of the peer and copy the section from that peer into another peer. Use the code snippet
provided on the Join a peer to a channel screen and paste it into the peer configuration for each peer. This will ensure
that the orderer override will work properly.
Importing nodes, MSPs, and identities

The console includes the option to import nodes that were created in another IBM® Blockchain Platform console.
blockchain network.
Why import components?

For cases when components have been deployed by one console and need to be operated from other, as well as for cases when
certain actions are not possible unless nodes and MSPs and identities are "known" to a console (that is, unless those
components have been created in the console or imported into it), the IBM Blockchain Platform allows nodes, identities, and
MSPs to be exported from one console and imported into another.
While it is no longer necessary to associate an admin identity when importing a node, there are cases where you will want to
import the admin identity associated with a node or MSP.

There are two main reasons to import components:
$ 1. A node will be deployed in one console and operated from another. In these cases, the relevant
admin identity must be exported and imported, or a new admin identity for the node must be created.
With the exception of upgrading the version of a node, it is possible to perform many of the same
administrative actions on an imported node as on a node that was created within a console.
2. A node or MSP simply has to be known by a console so that it can be selected from a drop down
list. For example, when creating a channel, it is necessary to choose which ordering service the
channel will be hosted on. Similarly, when performing many channel actions, it can be necessary to
specify one or more MSPs. In neither case is the person selecting the MSP an admin of the node or the
organization. However, they do require the tile representing the node or MSP in their console so it
can be selected from the drop down list.
Note that when you import a component, you do not actually import the physical component into your cloud provider. Instead,
the console uses the information in the JSON to build a representation of the component that can be operated from the console.
Likewise, when you delete an imported node from the console, the node itself, which is still running at the location where it was
deployed, is not deleted. It is simply removed from the console where it was imported.
After you import a node into the console, you can also modify its connection information by using the node'sSettings tab.
As you will see below, there are two ways to export and import components and identities: in bulk, or one at a time. Each fulfills a
different use case and has different considerations and limitations.
Limitations
While importing nodes provides the ability to perform many of the actions that can be performed on the console where a node or
identity was created, there are a few limitations on the ability to administer imported components:
All nodes to be imported must have been deployed by using the IBM Blockchain Platform console or IBM Blockchain
APIs.
You cannot patch nodes that have been imported into the console.
You cannot delete nodes that you imported into the console from the cluster where they were deployed. You can only
remove the node from the console it was imported to.
You cannot override the settings of an imported node by using the Edit configuration button to update the JSON.
If you are importing a node that is deployed on a network deployed locally, you must ensure that the gRPC web proxy port
used by the component is externally exposed to the console. For more information, see Importing nodes from a locally
deployed network.
When you open the tile of an imported node, the Fabric version is not visible and theUsage and info tab is not available,
even if you have also imported the admin identity.
Exporting and importing in bulk

In cases where users want to export and import all of the peers, CAs, ordering services, MSPs, and identities at once, the IBM
Blockchain Platform console now allows for the bulk management of data as a ZIP file that contains the JSON representing the
various nodes, MSPs, and identities. To export or import data in bulk, navigate to the Settings tab in the left hand navigation. You
will see a section called Bulk data management with two buttons below it. The Export button will open a panel on the right,
where you have several options of what to export. The Import button also opens a panel where you can select the ZIP from your
local file system.
While exporting and importing components in bulk is highly convenient for some use cases, there are important considerations
to keep in mind:
While you have the option to check or deselect the boxes representing peers, CAs, ordering services, MSPs, and identities,
you cannot, for example, choose to export only some peers and not others. If the peer box is checked, every peer will be
included in the ZIP, and likewise for other components.
If a console has already imported some of the information contained in a bulk transfer, for example a few of the peers,
duplicate representations of these components will appear in the console after performing the import. These duplicates

do no harm, but it is a best practice to only have one representation of a component at a time. The same duplication will
not occur when importing ordering nodes.
The Identities box is left deselected in the export panel by default for reasons we discussed earlier: these identities
contain private keys, therefore it is inadvisable to export them unless it is necessary to do so. Also, unlike MSPs and
nodes, the console does not permit duplicate identities. If you attempt to import a bulk data ZIP that includes an identity
that already exists in your console, the import will fail. Note once again that all identities will be sent in the bulk transfer,
regardless of the other boxes you check. For example, if you only leave the peer box selected, and select identities, every
identity in your Wallet will be sent, not just the identities relevant to the peer.
However, if you do choose to export identities along with nodes, the associations between identities and nodes will persist
along with the transfer. That is, you will not have to perform the extra step of clicking on nodes and associating an admin
identity with them.
It is necessary that all of the members of a channel have the MSPs of all of the other members of a channel to allow for
the validation of signatures. However, note that by selecting the MSPs button, all MSPs in your console would be exported,
not just the MSPs relevant to a particular channel.
If you import a bulk data transfer of nodes and do not also import identities, you will have to perform the separate step of
associating identities with the nodes. There are a few ways to procure an identity that can operate a node. For more
information about, see Gathering certificates or credentials. Regardless of the process used to acquire the identity, after the
bulk import has been completed you will need to click on each imported node. For peers and ordering nodes, a box on the left of
the screen will say Identity not associated with (peer or ordering node), depending on the node in question. After clicking on
this box, you will be able to associate the relevant identity by selecting it from your Wallet. Note that this process is distinctly
different than the process for importing individual nodes, where you will be asked to associate an identity as part of the import
process.
You will also need to associate an admin identity for the CA. This process is similar to the peer and ordering node process except
that after you click on the imported CA you will see a separate screen asking you to associate an identity rather than a box on the
left.
For cases where bulk data transfers are impractical or inadvisable, you can follow the steps below to export and import
components and identities one at a time.
Gathering certificates or credentials
Important: Because identities contain private keys, be careful when exporting them to ensure they are handled securely.
If a private key is compromised, it can be used to perform malicious actions.
Each IBM Blockchain Platform component is deployed with the signing certificate of an administrator inside. When actions
requiring the permission level of an admin are performed against the component, the signing certificate of the entity attempting
the action is checked against the signing certificate inside the node. If they don't match, the action is denied. In this way, these
certificates, which are also known as "keys", allow the administrator to operate their components.
If you intend to operate an imported node, you have two options:
1. Import the admin identity into your Wallet before importing the node itself (the administrator of the console where the
node was created will need to export the node and the admin identity).
2. If the admin of the node does not want to share their admin identity, there are two other ways to become an admin of the
node:
The administrator of the console where the node was created can create a new admin identity, associate it with the
node as an additional admin identity, and export that identity to your console along with the node.
The other option has five steps:
The admin of the CA that was used to create the relevant identities for the peer and peer organization can register a
new identity.
Then, they can send the enroll ID and secret of that identity to the importing console, as well as exporting the CA.
The importing console can then take the imported CA and use the enroll ID and secret to create a new identity.

This new identity would be sent back to the console where the peer was created and added as an admin of the
peer.
Then the peer could be exported to the console where the new identity was created, allowing the new identity to
operate the imported peer.
In either case, because this new admin identity would only be an admin of the peer and not the organization that owns the peer,
it preserves a separation of roles between the organization admin (the sign cert listed in the MSP, which might also be the peer
admin in the console where the peer was created), and the new admin of the peer which was just created and associated. This
peer admin would not be an organization admin by default. However, if it fits a use case to make an identity the admin of both
the organization and an imported peer, this is achievable, see Updating an organization MSP definition.
Note that this flow would be most practical for a peer, since the admins of ordering nodes do not have many responsibilities in
the IBM Blockchain Platform.
If you don't intend to operate the node (or in the case of a multi-node ordering service, the nodes), you do not have to import and
associate an admin identity.
Exporting and importing admin identities into the Wallet

To export an identity, open the Wallet tab and click on the identity you want to export. In theIdentity details panel that pops up,
you have two options. You can click the Export identity button, which will bundle your signing certificate and private key into a
JSON file, and download it to your local filesystem (note that you should always keep a copy of all your identities locally).
Alternatively, you can download .pem certificates for both your signing certificate and private keys.
To import a new identity, open the Wallet tab and click Add identity. If you want to upload .pem certificates manually, click
New identity and use the fields under Manual entry to give the identity a name and to upload the signing certificate and private
key of the identity. If you have a JSON that was exported from another console, click Upload JSON and then Add files, then
select the appropriate JSON from your local file system and click Add identity. While you will have this option between entering
certificates manually or using a JSON for each node, in this topic it is assumed that you have the relevant JSON handy.
After you complete the Add identity panel, you can view the new admin identity in your Wallet and select this identity when
importing any nodes it is associated with. You will also be able to use this identity when creating new MSPs and components.
Importing an organization MSP definition

Because MSPs define an organization, they are required when creating channels, creating nodes (to identify which organization
the node will belong to), and validating signatures. For the latter reason, your MSP must be known (in other words, exported
and then imported) by every member of every channel you belong to unless your organization will not be involved in
validation or endorsement.
To act as an administrator for an organization, you must have an identity in your Wallet listed in the MSP as an admin of the
organization. This means either importing the identity listed in the MSP or by following the process listed in Updating an
organization MSP definition. This MSP can then be exported to the console where the added identity was created, making the
exported identity able to act as an admin of the organization.
The exports and imports of MSPs are performed in the Organizations tab.
To export your MSP:
1. Navigate to the Organizations tab and click your organization MSP tile.
2. In the tile that opens, click the Export icon.

Figure 1. Export MSP button
3. A JSON file is generated and downloaded to your local system.
4. Share this file with the other organization admins of your channel.
To import an MSP from another organization:

Note: Under some circumstances, it is possible that the Node OU checkbox may be visible and checked when you import an
MSP into your console. If that occurs, it is recommended that you leave it checked so that it enables Fabric Node OU support for
the MSP, which simplifies the certificate renewal process for you in the future.
Repeat these steps for each organization that is included in your channel.
Importing a peer
A peer is the blockchain component that maintains a ledger and runs a smart contract to perform query and update operations
on the ledger. Organization members own and maintain peers. Each organization that joins a consortium should deploy at least
one peer and minimally two for High Availability (HA) on each channel. You can learn more about peers in the overview of
blockchain components.
After you import a peer into the console, you can install smart contracts on the peer and join the peer to channels.
Note: If you want to add more peers or create additional admin identities for a peer or peer organization, you need to import the
relevant CA (the one that was used to create the MSP and identities for the peer organization) and then use that CA to register
and enroll identities.
Before you begin

Before you can import a peer, you need to decide on the method you will use to become an admin of the peer (there is little that
can be accomplished with an imported peer unless you also are an admin of the peer). See, Gathering certificates or credentials
and follow the path that best suits your use case. Also, ensure that the JSON representing the peer is available.
How to import a peer

Importing a peer is performed from the Nodes tab.

1. Click Add Peer, followed by Import an existing peer and then click Next.
2. Click Add file to upload the peer JSON file that was exported from the console where it was originally deployed.
3. If you want to operate the peer (for example, to be able to install smart contracts), click on the tile representing the peer
and click Associate identity. Then you will be able to associate an identity from your Wallet with the peer. This identity
must be identity that was associated with the CA when it was created.
Note: If you see the location field during import, you can choose whether to specify the location where the peer was
created or to have the peer re-exported, in which case the console will not ask for this information.
After you import the peer into the console, you can install smart contracts on the peer and join the peer to channels in your
blockchain.
Importing a CA
A CA node is the blockchain component that issues certificates to all network entities (peers, ordering services, clients, and so
on) so that these entities can communicate, authenticate, and ultimately transact. Each organization has their own CA that acts
as their root of trust. You should add your organizations whether you are joining or building a blockchain consortium. You can
learn more about CAs in the overview of blockchain components.
After you import a CA, you can use it to register and enroll users or create organization definitions exactly as you would with any
other CA.
To import a CA to the IBM Blockchain Platform console and operate it, the network operator must have already exported the CA
from the IBM Blockchain Platform where it was deployed. Importing a CA allows you to register new users and enroll identities.
Before you begin

Before you can import a CA, you need to decide on the method you will use to become an admin of the CA (there is little that can
be accomplished with an imported CA unless you also are an admin of the CA). See, Gathering certificates or credentials and
follow the path that best suits your use case. Also, ensure that the JSON representing the CA is available.
How to import a CA
1. Click Add Certificate Authority, followed by Import an existing Certificate Authority, and click Next.
2. Click Add file to upload the CA JSON file that was exported from the console where it was originally deployed.
3. If you want to operate the CA, after it has been added, click on it in theNodes panel. Then click Associate identity and
select the CA admin identity from your Wallet.
Note: If you see the location field, you can choose whether to specify the location where the CA was created or to have
the CA re-exported, in which case the console will not ask for this information.
After you have imported the CA into the console, you can use your CA to create new identities and generate the necessary
certificates to operate your components and submit transactions to the network. To do this, you will need to associate an admin
identity with the CA. To learn more, see Managing certificate authorities.
Importing an ordering service

An ordering service is the blockchain component that collects transactions from network members, orders the transactions, and
bundles them into blocks. It is the common binding of blockchain consortiums and needs to be deployed if you are founding a
consortium that other organizations will join. You can learn more about ordering services in the overview of blockchain
components.

Importing an ordering service into the console allows you to create new channels for peers to transact privately.
Tip: If you are having trouble with an ordering service you imported, it might be because it was exported too long ago for
the JSON representing it to have all of the latest necessary fields in it that allow certain features to work. Reach out to the
administrator of the console where the ordering service was created and ask them to re-export the ordering service.
Before you begin

Even in the world of Hyperledger Fabric, ordering node admins do not have many responsibilities. In the IBM Blockchain
Platform, these responsibilities are reduced even further, and because of the Limitations imposed on imported nodes, these
responsibilities are reduced to nothing. As a result, there is not much point in becoming an additional admin of an ordering node.
If your orderers are using a system channel, it is far more useful to become an admin of the ordering organization itself. This role
gives you administrative rights over the ordering service (allowing you to add organizations to the consortium or nodes to the
ordering service) as well as over the system channel, giving you the permission to modify system channel capabilities.
Note that it is not necessary for your organization to become an ordering service administrator. You will still need to import the
ordering service if you want to create or edit a channel (your organization must be added to the consortium by an ordering
service administrator first), as your console must know about the ordering service before you can select it from the drop down
list.
How to import an ordering service

1. If you have not already done so, navigate to theOrganizations tab and export the MSP of one or more peer organizations.
Then, send this MSP, which represents your organization, to an administrator of the ordering service (which in this case is
not necessarily an admin of any ordering nodes, but an organization with administrative control over the system channel).
This ordering service administrator can make your organization one of the ordering service organizational admins or add
your MSP to the consortium (giving your organization the ability to create channels), or both. Note that if your organization
has been made one of the ordering service organizational admins, you have the ability to add your own organization to the
consortium.
2. After your MSP has been added as an ordering service administrator or to the consortium (or both), import the JSON
representing the ordering service (as with the other nodes, this ordering service must be exported from the console where
the ordering service was created). Then, navigate to the Nodes panel. Click Add ordering service, followed by Import an
existing ordering service. Then click Next.
3. Click Add file to upload the ordering service JSON. Note that regardless of how many nodes are in this ordering service,
the JSON representing this ordering service will be one file.
It is not necessary to associate an identity with an ordering service in order to create a channel on an ordering service or to join
members to the consortium (the latter is handled by ordering service organizations, not the ordering node itself).
Note: If you see the location field, you can choose whether to supply the location or to have the ordering service re-
exported, in which case the console will not ask for this information.
After you have imported the ordering service into the console, you can add new organization members to the consortium (if your
MSP was added as an admin of the ordering service) and select the ordering service when creating new channels (if your
organization has been added to the consortium).
Importing nodes from a locally deployed network

You can import nodes that were created through IBM Cloud, Red Hat OpenShift, and Kubernetes v1.23 - v1.24 environments
into blockchain consoles that have been deployed on other clusters or on IBM Cloud. However, you need to ensure that the port

used by the gRPC URL of your nodes is exposed from outside the cluster. If you are deploying your network behind a firewall, you
need to enable a passthru, for example by using an allowlist, to allow the console outside the cluster to communicate with your
nodes.
As an example, you can find the JSON file of a peer below. To communicate with the peer from another console, you need to
ensure that the grpcwp_url port, port 32403 in this example, is open to external traffic.
{
"name": "peer",
"grpcwp_url": "https://9.30.252.107:32403", \\ensure that port 32403 is externally exposed
"api_url": "grpcs://9.30.252.107:30891",
"operations_url": "https://9.30.252.107:30222",
"type": "fabric-peer",
"pem":
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNGekNDQWI2Z0F3SUJBZ0lVUi9zMGxGTG5ZNmdWRmV1Mlg5ajkrY3JDZFBr
d0NnWUlLb1pJemowRUF3SXcKWFRFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ
1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVE0d0RBWURWUVFERXdWMGJITmpZVEFlCkZ3MH
hPVEEyTVRBeE9USXhNREJhRncwek5EQTJNRFl4T1RJeE1EQmFNRjB4Q3pBSkJnTlZCQVlUQWxWVE1SY3cKRlFZRFZRUUlFdzVPYjN
KMGFDQkRZWEp2YkdsdVlURVVNQklHQTFVRUNoTUxTSGx3WlhKc1pXUm5aWEl4RHpBTgpCZ05WQkFzVEJrWmhZbkpwWXpFT01Bd0dB
MVVFQXhNRmRHeHpZMkV3V1RBVEJnY3Foa2pPUFFJQkJnZ3Foa2pPClBRTUJCd05DQUFUYUtyN2srUHNYeXFkWkdXUHlJUXlGMGQxU
kFFdmdCYlpkVnlsc3hReWZOcUdZS0FZV3A0SFUKVUVaVHVVNmtiRXN5Qi9aOVJQWEY0WVNGbW8reTVmSkhvMXd3V2pBT0JnTlZIUT
hCQWY4RUJBTUNBUVl3RWdZRApWUjBUQVFIL0JBZ3dCZ0VCL3dJQkFUQWRCZ05WSFE0RUZnUVUrcnBNb2dRc3dDTnZMQzJKNmp2cEl
QOExwaE13CkZRWURWUjBSQkE0d0RJY0VDUjc4YTRjRXJCRE5DakFLQmdncWhrak9QUVFEQWdOSEFEQkVBaUJGWmpMWU9XZUMKLy92
L2RNMHdYNUxZT3NCaHFFNnNQZ1BSWWppOTZqT093QUlnZEppZDU0WmxjR2h0R3dEY3ZoZE02RVlBVFpQNwpmS29IMDZ3ZFhpK3VzV
XM9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
}
Creating and managing identities

The nodes of the IBM Blockchain Platform are based on Hyperledger Fabric and builds permissioned blockchain networks. This
means that all participants of the blockchain consortium need to have identities that are continuously verified by Public Key
Infrastructure. The IBM Blockchain Platform console allows you to create these identities by using your organization's Certificate
Authorities (CAs). You need to store these identities in your console wallet so you can use them to operate your network.
blockchain network.
Managing Certificate Authorities (CAs)

A CA is similar to a publicly trusted notary that acts as an anchor of trust among multiple parties, with each organization in a
consortium maintaining their own CA. Your CA creates the identities that belong to your organization and issue each identity a
signing certificate and private key. These keys are what allow all of your nodes and applications to sign and verify their actions.
For more information about how CAs are used to establish identity, see the identity topic in the Hyperledger Fabric
documentation.
When you create a CA by using the IBM Blockchain Platform console, two CAs are created with the same endpoint URL: a root
CA and a TLS CA. The root CA provides keys to your nodes and applications. The TLS CA provides certificates that are used to
protect the communication within your network. To learn more about TLS on your network, see Using your TLS CA.
When you create your nodes, you need to use your root CA to create the following identities that are required to deploy, operate,
and interact with your network:
CA admin: Your CA contains a default CA admin identity. This identity has an enroll ID and secret, which are analogous to
a username and password, that you specify during the deployment of your CA. You can use this admin username and
password to operate your CA and create new identities. The CA admin of your root CA is also the admin of the TLS CA.
Peers or orderers: You need to register an identity for each of the peers and orderers that belong to your organization.
Your nodes will then use these identities during deployment to generate the keys they need to participate in the network.

For security, create a unique enroll ID and secret for each node you deploy.
Org admins: When you join a consortium that is hosted by an ordering service, you provide the signing certificates of
identities that will become the administrators for your organization. You can use these identities to create or edit channels.
Peer or orderer admins: IBM Blockchain Platform nodes are deployed with the signing certificates of component
administrators identities inside of them. These certificates allow the admins to operate the component from a remote
client or by using the console.
Applications: Your applications need to sign their transactions before submitting them to be validated by the network.
You need to create identities you can use to sign transactions from your client applications.
You can use the console to create these identities by using the registration process. After you register your admin identities, you
need to issue each identity a signing certificate and private key, provide the signing certificate to your organization MSP
definition, and add the identity to your console wallet. You can complete these steps for one admin identity when you create
your organization MSP. You can use separate identities as org admins or node admins, or you can use one identity to do both
tasks. The Build a network tutorial uses one identity to be an admin for each organization created in the tutorial.
Associating the identity of the CA admin

Before you can create identities, you need to associate the identity of the CA admin. Open your CA on theNodes tab. If you are
using the CA for the first time, you can click the Associate identity button to generate the CA admin identity and import it into
your console wallet. On the Associate identity side panel, provide the Enroll ID and Enroll secret of the CA admin that you
provided when you created the CA.
You can view the enroll ID of the associated admin on the left side of the CA panel, below the CA name, Node location, and
Fabric version. You can use this identity to create other identities by using the Register button. The CA admin also allows you to
get the list of registered identities, and then use these identities to generate certificates by using the Enroll button.
To use a different identity as the CA admin, click the identity that is associated with the CA admin. This opens theAssociate
identity side panel. You can use the Enroll an identity tab to provide the enrollID and secret of another CA admin. You can
specify an identity that exists in the wallet by using the Select an existing identity tab.
Note: You can only use admin identities to register new users. You can create new admins with restrictions on the type of
users they are allowed to create. As a result, you can let another user operate your CA by providing them an admin that is
not able to create admins or deploy nodes. This allows other members or departments of your organization to access your
CA without compromising your network. For more information, see Creating new CA admins.
Registering identities
The first step in creating an identity is known as registration. During registration, an enroll ID and secret are created which can
be used by a node or an org administrator to enroll this identity by generating a signing certificate and private key.
You need to enter the following information when you register a new identity with your CA.
Enroll ID and Enroll Secret: This identity has an ID and secret, which is analogous to a username and password, that you
specify during the deployment of your CA. You can use this admin ID and secret to create certificates with this identity by
using this console or the Fabric CA client.
Type: When the CA was deployed, the administrator specified the types of identities issued by the CA. Common examples
of identity types include peer, orderer, admin, and client (applications). Select the identity type for this user from the list of
available types.
Affiliation: (Optional) Advanced users only. This field is only visible if affiliations are defined for your CA. An affiliation is
the part of an organization that you want to associate with this user. For example, this could be a department or unit that
operates an application or a peer. It is possible to restrict a particular CA admin to be able to register only users within
their own department within an organization by setting their affiliation. CA affiliations are defined by using the Fabric CA
Affiliation Command. The default affiliation that is available when you clear the Use root affiliation checkbox is ibp.
Maximum Enrollments: Optionally, enter the number of times that you can enroll or generate certificates by using this

identity. Specifying a limited number of enrollments helps protect the security of your nodes and applications. It defaults
to unlimited enrollments.
Attributes: Optionally, you can specify any attribute-based access control attributes for the user. For example, you can
use this section to create another CA admin with authority to register and enroll new identities. You can see a full list of
available Fabric CA attributes in the Registering a new identity section of the Fabric CA users guide.
Click the Register user button on the CA overview panel to create a new user. Be sure that you have set the identity to a CA
admin that has the ability to register new users before you attempt this task. In general, this is your admin user. If the button is
gray, you have either not set an identity, or that the identity cannot create new identities.
Clicking Register user opens a series of side panels:
1. On the first side panel, enter the Enroll ID and Enroll Secret of the new identity. Save these values, as they are not stored
by the console.
2. Select the identity Type. The drop-down list contains the list of types that the CA supports. If you are registering an
identity that will serve as an admin of a node, select type admin. If you are registering a peer identity select peer and
likewise for an ordering node identity select orderer. When you need to register an identity for a client application select
the type client.
3. You can associate an affiliation with the user. Check the Use root affiliation checkbox for the user if you want them to
have the root affiliation and be able to see all other users registered with this CA. When you deselect Use root affiliation,
you can select a specific affiliation from the list to associate with this user. The platform includes the default affiliation
ibp.
4. Enter the Maximum Enrollments allowed for this identity. If not specified, the value defaults to unlimited enrollments.
5. On the last side panel, add the Attributes of the identity you are creating.
After you click Register, the new identity will be added to the list ofAuthenticated users that have been created by your CA. The
identities are listed by their Enroll ID, along with their Type and Affiliation. Clicking on an identity in the table opens a side panel
that displays the number of Maximum Enrollments and Attributes that were created during registration.
Deleting a user
If you need to delete a registered user, click the action menu next to any user and select Delete user. If that option is not
available, it can be enabled on your CA by overriding the CA configuration. See an example of how to enable this feature in
Modifying a CA configuration after deployment. Note this action does not revoke the associated certificates for the user. If you
need to do that you would need to insert the associated signed certificate into the organization MSP under the
"revocation_list": section. And then update that MSP definition everywhere that it occurs on the network.
Creating new CA admins

By default, only the CA admin that is created during deployment has the ability to register new identities. You can create
identities with the ability the register new users by using the Attributes panel of the registration process.
On the second side panel, click the Add Attribute button. Provide an attribute name of hf.Registrar.Roles . Enter an
attribute value of * . You can also use this panel to create an identity that can register only certain identity types, such as clients
or peers, or within a certain affiliation. You can also create an identity that has the ability to revoke an identity and all the
certificates that the identity has been issued. You can see a full list of the attributes in the Registering a new identity section of
the Fabric CA users guide.
Enrolling an identity
You can generate the signing certificate and private key for each user that is registered with your CA. If you registered additional
admin identities with your CA, you can generate the certificate and key for the admin identity and then include the certificate
when you create your organization MSP.
Before you enroll an identity, you need to Associate the identity of the CA admin to be able to operate the CA. If the identity is
not set, you will not be able to view the Registered Users table on the CA panel. In the Registered users table, navigate to the

action menu for the user and click Enroll identity to generate the certificate and key for any user registered with the
CA.
Under the Certificate Authorities dropdown, select Root Certificate Authority.

Enter the user's Enroll secret.
(Optional) In the CSR Hostname field, enter the Subject Alternative Names (SAN) to embed in the generated
certificate. Specify the host names or custom domain name where the certificate is valid. You can specify a comma
separated list of hosts as well as include a wildcard in the domain. For example, 'host1, host2, *.example.com . If you
leave this field blank, the SAN inside the generated certificate is empty.
On the next step, the generated keys are displayed.
The signing certificate is displayed in the Certificate field. This certificate is also referred to as your enrollment
certificate, signing certificate, or signCert.
You can find the corresponding private key in the Private Key field. Again, you need to export the private key to your
local system for use with a client application created with the VS Code extension.
The certificate and private key that are created by clickingEnroll Identity is only generated once and not stored by
the console or your browser. Clicking the Enroll Identity button is counted against the maximum number of
enrollments that you set for the identity. You should store the signing certificate and private key by downloading the
identity to your local file system or adding it to your console wallet. Enter a new name for this signing certificate and
private key into the Name field in order to retrieve them.
Important: Click Export identity to download the certificate and key to your local file system as a single file in JSON
format. You are responsible for securing and managing these keys.
Click Add identity to wallet to add these certificates to the console wallet. You can then find the name and keys of this
identity in a new tile in your wallet tab
You can also use the Fabric CA client or Fabric SDKs to enroll the identities you create in the console. The console provides you
with all of the information that need to compete these steps. Ensure that you have saved the Enroll ID and Enroll secret that you
specified during registration.
Using your TLS CA

The communication within your network is secured by TLS certificates. TLS encrypts the communication between your nodes
and between your nodes and your applications. Using TLS prevents attackers from disrupting the communication between your
nodes or reading the transactions that are submitted from your applications. The keys and certificates that are used for TLS are
different than the certificates used to sign and validate your transactions and are issued by a separate Certificate Authority.
Each CA created by the IBM Blockchain Platform console contains a root CA and a TLS CA. Both of these CAs use the same
database and share the list of registered users. As a result, each identity that is registered with your root CA is automatically
registered with your TLS CA as well. The CA admin of your root CA is also the admin for your TLS CA.
You can use each identity in the Registered Users table to generate TLS certificates. Follow the same process as you used to
enroll an identity by using your root CA. However, on the Enroll identity panel, select the TLS Certificate Authority from the
Certificate Authorities drop-down list.
Each peer or orderer node that you deploy needs to generate a public TLS certificate. When you create peer or orderer nodes,
you can use the same enroll ID and secret that you used to generate the peer or orderer identity as the TLS enroll ID and secret
because the TLS CA uses the same user repository as the organization CA. The node then uses this identity to generate its TLS
certificate during deployment. This certificate is required by any application that needs to communicate with the orderer or peer.
You can find the TLS certificate of a node by navigating to the node overview panel and clicking Settings. You can also find the
TLS Certs of your peers and orderers in the connection profile that can be downloaded from the organization MSP tile on the
organizations tab.
When creating a peer or orderer with your console, you can also use the TLS CA to specify an additional domain name for each
node. Enter the new domain name in the TLS CSR hostname field when deploying your orderer or peer. This hostname will be
added to the list of common names in the TLS certificate issued to your node.

Certificate renewal and expiration
Certificates expire and need to be renewed regularly in a process referred to as "certificate rotation". In a production network,
you need to monitor the expiration dates of the various certificates and make plans to renew them before they expire. The
platform attempts to automatically renew the enrollment certificates of the peer and ordering nodes 30 days before they expire,
but you are responsible for manually renewing the organization admin certificates for your nodes, system channels and
application channels. It is recommended that you review the topic on managing certificates to learn more about what is
required.
Storing identities in your console wallet

The wallet stores the identities and keys that the IBM Blockchain Platform console uses to operate the nodes of your network.
You need to add your peer, orderer, and organization admins to this wallet before you can use the console to work with channels
and smart contracts. You can also use the wallet to conveniently store the identities you use for your applications. You can use
the wallet to export them at any time. Use the left navigation to browse to the wallet overview panel. You can add, update, and
export identities from this wallet by using the overview panel.
Important: The wallet is a component of the console and not a separate service. It stores your keys in the local storage of
the browser that you use to access the console instead of your local file system. If you access your console from a
different browser, or start a private browsing session, you will not be able to access the identities stored in the wallet. It is
recommended that you export your admin identities from the console and store them in a safe place.
Adding identities
You can add an admin identity to your wallet when you create your organization MSP. A CA managed by the console can also
add an identity to your wallet during the enrollment process.
You can use the Add identity button on the overview panel to import an identity directly into the wallet. Clicking this button
opens up a side panel that allows you to add an identity's signing certificate and private key.
Name: Enter an identity name that is used for your reference only.
Certificate: Upload a file that contains the identity's signing certificate (in base64 or PEM format) that you generated by
using your CA.
Private Key: Upload a file that contains the identity's private key (in base64 or PEM format) that you generated by using
your CA.
You can also add an identity by uploading a JSON file in the format below. You can also use theUpload JSON button to upload
multiple identities at once.
{
"name": "peerAdminCerts",
"private_key":
"LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tDQpNSUdIQWdFQU1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhCRzB3YXdJQkFR
UWdIVk5Kc0tHYnl6eTVZWEQ2DQovaEhKOVZlR0QrZVhmenpxUi9PQWVZYnY5UWloUkFOQ0FBUmZ1WlB1OTRzNnJQSEVCMjJlWFhpS
Wozd0lKYkg4DQpRYVpaRkJlNFp5SnU5UllHbkxQWUdLRnhETkRVMUZkU1NxUGNLcnczUXpxT3hXNU1NZDVWbEtVdw0KLS0tLS1FTk
QgUFJJVkFURSBLRVktLS0tLQ0K",
"cert":
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlCNURDQ0FZdWdBd0lCQWdJVUhhUFNNdlcxOEwyaGNTeGlJK1ZqT1d0Wnly
Z3dDZ1lJS29aSXpqMEVBd0l3YTHJNM1o5TUZicGt3SGthYnB0MmZBekFLQmdncWhrak9QUVFEQWdOSEFEQkVBaUFmdUhjY2R6WExq
Z3BLDQplVFhnNmNNcnRzRUs4ZVlKTVFMNlZLU0xwUXIvN3dJZ1hyK2ZuVjUrb2RHWnNRUU94SjZ1aDVTV0tJVkdZQ2ZGDQp1Ykw4V
mJNdnRRZz0NCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0NCg=="
}
If you did not enroll an identity from the console, but instead by using the Fabric CA client or the Fabric SDKs, your keys need to
be converted from PEM format into base64 format. You can convert certificates into base64 format by running the following

cat $HOME/<path-to-certificate>/cert.pem | base64 $FLAG
Viewing and updating identities

From the Wallet tab, click a tile to view, update, or remove an identity from the wallet. It might be necessary to update your
identities if their certificates have expired, and they need to be issued new keys from the CA. You can also use this tab to delete
keys from your console and your local system.
Clicking an identity opens a side panel that displays its certificates and private keys in base64 format. Click the download button
to export both the certificate and the private key as a .pem file to your local file system.
How to Export cert and private key
Click Update to change the identity name in the wallet or paste a new set of keys into the panel. ClickRemove when you no
longer need to use this identity and want to delete its keys.
IBM Blockchain Platform can auto-renew the enrollment (signing) certificates for the peer and ordering nodes and the peer TLS
certificate. For the other certificates, you can see certificate types and actions to learn on how to maintain them.
A one-stop solution is available for easy management and maintenance of your certificates; see IBM Secrets Manager for
details.
Downloading certificates
You can download IBM Blockchain Platform certificates from the console, in PEM format, for viewing certificate expirations. This
includes all peer, Certificate Authority (CA) and orderer node certificates.
Navigate to the console tab for the desired node and select the download icon forEnrollment Cert Expiration or TLS Cert
Expiration.

How to download certs
You can then save the downloaded PEM file for viewing or importing.
Storing identities in a Hardware Security Module (HSM)

In a production environment you have the option to generate and store private keys in an HSM. An HSM is a hardware appliance
that performs cryptographic operations and provides the capability to ensure that the private keys never leave the HSM. The
HSM then allows your peers to sign and endorse transactions without exposing their private keys. Fabric supports HSM devices
that implement the PKCS11 standard. PKCS11 is a cryptographic standard for secure operations, generation, and storage of
keys.
There are three ways you can use an HSM with the IBM Blockchain Platform:
1. Utilize the HSM appliance that is available in IBM Cloud.

2. Configure your own HSM.
3. For test purposes only, configure open source SoftHSM. You can use SoftHSM for cryptographic operations of your peer,
ordering node or CA inside an HSM partition.
After you have configured an HSM, you need to configure a HSM proxy that allows the blockchain node to communicate with the
HSM. Then when you configure a blockchain node, you will need to provide three pieces of information:
Proxy endpoint: ClusterIP address that is generated for the HSM when the HSM proxy is configured.
Label: Corresponds to the HSM Partition.
PIN: The PIN associated with the HSM slot.
After HSM is configured for a node, the HSM becomes the cryptographic service provider for the node. When the HSM is
subsequently used to generate and store a node's private key, and the node identity is exported or stored in the wallet, the
private key is not visible.
For more information about how to deploy the HSM proxy and use HSM with a CA, peer, or ordering node, see Configuring a
node to use HSM
Associating identities
You need to provide the signing certificate of your organization and node admins to your organization MSP definition. The nodes
or channels that are created by the console uses the certificates from the MSP definition to check who is a valid administrator. As
a result, the same signing certificate and private key that you used to add an admin cert to the MSP definition needs to be stored
inside your console wallet.

When you use the console to create an orderer or peer, you will encounter anAssociate identity panel. Select an identity in the
wallet whose certificate is also inside your organization MSP definition. You will also need to select an admin identity in the
Associate identity section when you create or edit a channel. This allows your console to know which identity to use when it
communicates with your peers, orderers, and ordering service consortium. The identity that is currently associated with a peer or
ordering service is visible on the left side of the node panel, below the name, Node location, and Fabric version.
Viewing the contents of a signing certificate

As a network operator, there may be situations when you need to view the contents of a signing certificate, or sign cert, to debug
a problem. If you have the certificate PEM file, you can run the following openSSL command to print out the certificate contents:
openssl x509 -in <certificate.pem> -text -noout
Replace <certificate.pem> with the sign cert file and the output will resemble the following content:
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
68:b9:6d:d3:00:1e:1b:9d:4b:99:1e:ab:ed:05:48:be:28:51:69:3d
Signature Algorithm: ecdsa-with-SHA256
Issuer: C=US, ST=North Carolina, O=Hyperledger, OU=Fabric, CN=fabric-ca-server
Validity
Not Before: Nov 20 19:08:00 2019 GMT
Not After : Nov 19 19:13:00 2020 GMT
Subject: OU=client, OU=org1, OU=department1, CN=user1
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (256 bit)
pub:
04:11:0c:c9:9e:47:d8:38:aa:c7:24:65:90:98:a3:
42:a8:b0:18:3e:03:43:13:ae:64:6a:18:93:6e:06:
23:30:09:c1:93:66:5f:0d:d6:37:1b:a0:c4:e9:cb:
9b:70:63:9a:af:08:20:f2:96:b8:de:3b:c5:6e:58:
a9:9e:fa:d6:de
ASN1 OID: prime256v1
NIST CURVE: P-256
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature
X509v3 Basic Constraints: critical
CA:FALSE
X509v3 Subject Key Identifier:
E4:86:14:C1:58:21:D8:6F:B4:79:E5:41:3B:14:9B:3D:C6:36:87:36
X509v3 Authority Key Identifier:
keyid:70:CA:7D:2E:5A:75:A2:90:27:8C:5D:7D:C7:AF:F1:2C:E1:25:59:70
1.2.3.4.5.6.7.8.1:
{"attrs":
{"hf.Affiliation":"org1.department1","hf.EnrollmentID":"user1","hf.Type":"client"}}
30:44:02:20:1a:38:64:47:69:6b:31:e4:96:bc:52:06:71:75:
9e:01:57:a4:bd:b0:15:f0:19:c4:23:37:29:14:b1:66:e3:ce:
02:20:7a:34:af:7b:fb:65:6c:b8:22:a2:39:78:5d:30:5c:3c:
b0:9b:0e:14:d8:76:78:9a:34:2b:bb:d2:97:d4:ce:81
Managing organizations
You can use the IBM® Blockchain Platform console to create a formal organization definition that is known as a Membership
Services Provider (MSP). Your organization's MSP definition allows other members of the blockchain consortium to verify the
identity of your nodes and applications. Your MSP definition also contains your organization's admin certificates.

You can also use the console to manage which organizations are members of your channel. The administrator of the ordering
service can use the organizations tab to add members to the blockchain consortium. Members of the channel can then use the
console to add members to new or existing channels.
Figure 1. You can use the organizations panel to create, import, and manage organization MSP definitions
blockchain network.
Understanding MSPs
The IBM Blockchain Platform is based on Hyperledger Fabric and builds permissioned blockchain networks. Participants need to
be known to the network before they can submit transactions and interact with the assets on the ledger. Fabric recognizes
identity through a group of invited organizations at the channel level. Organizations in the consortium are able to issue valid
credentials to their members and let them become participants in the network. The participants can then operate blockchain
nodes and submit transactions from client applications.
Each organization in a network needs to operate a Certificate Authority to create all of the identities for the admins and nodes
that belong to your organization. These public-private keys pairs are issued by the CA and used by the members of your
organization to sign and verify their actions. When an organization joins a channel, the public key of the CA associated with that
organization allows other organizations to verify that your peers and applications are valid participants. For more information
about membership in Hyperledger Fabric, see the Membership concept topic in the Fabric documentation.
Before your organization can join a consortium, it needs to create an organization definition that is known as aMembership
Services Provider (MSP). The MSP contains the following information:
A certificate signed by your root Certificate Authority. This certificate is used to verify the identity of your nodes, channels,
and applications.
A certificate signed by your TLS CA. A root TLS certificate allows your peers to participate in cross organization gossip,
which is necessary to take advantage of the Private data collections and Service Discovery features of Hyperledger Fabric.
The MSP ID. The MSP ID is the formal name of your organization. You need to remember the MSP ID for your applications
or when using the SDK to submit transactions.
The MSP display name. This is an informal name that is given to your organization, which is used to identity your MSP in
the console.
The Admin certificates of your Organization Admin identities. These certificates are passed to the ordering service and
are used to verify which identities in your organization are allowed to create or edit channels. When you use your console
to create an ordering node or peer, the admin certificates inside the MSP are deployed within the new node, making your
organization admin identities your peer or orderer admins as well. You can use these identities to operate your node, such
as by installing a smart contract on a peer or joining a peer to a channel, from your console or a client application.
Managing MSPs in the console

Navigate to the Organizations tab. You can use this tab to create an MSP definition by using a Certificate Authority that exists in
your console. You can also use this tab to import an MSP that was created by another organization.
You can view all of the MSPs that you created or imported underAvailable organizations. You can use the MSP definitions in the
organizations tab for important functions within your console:
If you are creating peer or ordering nodes, the MSP of your organization is used to identify the organization that the node
belongs to.
MSPs are used by organizations to verify the signatures of actions by other organizations. For this reason, you should
export your MSP to every organization in the channel and likewise import the MSP of every organization.
If your organization is one of the admins of the ordering service, you can add new organizations to the consortium.
If you are a member of the channel, you can import the MSPs of other organization into your console and then add the
members to new or existing channels.
You can click an MSP definition in the organizations tab to view all of the nodes in the console that belong to each organization.
Because each node was deployed with the administrator certificate from the MSP definition inside, you can use this panel to
know which nodes are managed by which organization administrator.
Creating an MSP for your organization

Use the Organizations tab to generate an MSP definition for your organization. When you click Create MSP definition, a panel
will open in which you will enter all the necessary information for your MSP.
The MSP definition details tab is where you provide a display name and an MSP ID for the MSP. Use the tooltip to learn
about the restrictions for the MSP ID.
Important: If your organization is joining an ordering service with other organizations, to avoid confusion, it is strongly
recommended that every organization have a unique MSP ID. In other words, you should never use the same MSP ID to
represent different organizations on a network.
The Root Certificate Authority details tab is where the CA for your organization is specified. This is the CA that you use to
register all of the identities associated for your organization. Before creating an MSP, you must register the admin of the
MSP. If you use intermediate CAs, this is the CA that you used to create those CAs. Select your CA from the list of CAs
managed by using your console. If you created a CA using the console, selecting a CA will also display the root TLS
certificate of your TLS CA, which was deployed alongside your CA.
You can also use the Admin certificates tab to generate the identity of your organization admin. If you already have an
admin identity you want to make your organization admin, click Existing identity and select the identity from the drop-
down list. If you want to use the panel to generate a new admin identity, you need to register your organization admin with
your CA. You then need to complete the following steps in order to use these identities to operate your network:
1. Enter the Enroll ID and Enroll secret of an admin identity that is registered with your CA. After you enter the enroll
ID and enroll secret, choose a Display name. This name is used to represent the identity in the console.
2. Click Generate. This generates a certificate and private key and automatically add the keys to your Wallet. You can
then find your admin identity in your Wallet by using the name that you selected on this panel. These keys are only
stored in your browser local storage. Therefore, if you change browsers, they will not be in your Wallet. This is why
you should click Export to export this identity to your local file system. If you switch browsers, you will need to
import the identity from your file system into the Wallet of your new browser.
3. Then, click Export to download the key pair to your file system and secure them.
The Administrators certificate section of the side panel contains the signing certificates keys of your admins. The
certificate that you generated by clicking Generate in the section above can be found in the first row of the field. If you
want to use multiple admin identities to operate your network, you can paste additional certificates into admin certificate
fields.

Because your admin certs are passed to your nodes and channels by using the MSP definition, you need to ensure that each of
your node and organization admin certificates is stored in the MSP. When you use the console to create an orderer, peer, or
channel, you need to Associate one of the identities you exported in your Wallet with the admin certificates that were provided
to the MSP definition. When you encounter an Associate identity section or panel, select an identity that you generated and
saved to the Wallet when creating the MSP definition.
On the Review MSP information panel, review the information that you specified for this MSP.
After you have selected your CA, MSP ID, and either specified or created an admin, clickCreate MSP definition. It should now be
listed as an organization in the Organizations tab. Because an MSP is the representation of an organization in the network, you
select the MSP definition when you deploy your nodes (identifying the organization the node belongs to), are joined to the
consortium (by an ordering service admin), create a channel, join a channel, edit a channel, or perform any action where you
have to specify the organization that is performing the action.
Downloading a connection profile

After you create an organization MSP definition and create peers with that organization MSP definition, you can download a
connection profile that can be used by a client application to connect to your network via one or more gateway peers. The
gateway peers are the peers that are specified in the connection profile, and they are used to perform service discovery to find
all of the endorsing peers in the network that will endorse transactions.

Including a certificate authority in a connection profile

If you plan to use a client application to register and enroll users with the organization CA, then you need to include the
associated CA in the connection profile.
If the CA that is associated with the MSP resides in a different console, when you attempt to download the connection profile
you see a warning message and the "certificateAuthorities:" section of the generated connection profile is empty.
Figure 3. You can use the organizations panel to create, import, and manage organization MSP definitions
The generated connection profile without the CA information resembles:
$ {
"name": "org1profile",
"description": "Network on IBP v2",
"version": "1.0.0",
"client": {
"organization": "org1"
},
"organizations": {
"org1": {
"mspid": "org1",
"certificateAuthorities": [
"xyz-ca.openshift-ibpv2-test-1-0001.us-south.containers.appdomain.cloud:443"
],
"peers": [
"va0414-ba-peer.openshift-ibpv2-test-1-0001.us-south.containers.appdomain.cloud:443",
"va0414-peer.openshift-ibpv2-test-1-0001.us-south.containers.appdomain.cloud:443"
]
}
},
"peers": {
"xyz-peer.openshift-ibpv2-test-1-0001.us-south.containers.appdomain.cloud:443": {
"url": "grpcs://xyz-peer.openshift-ibpv2-test-1-0001.us-
"tlsCACerts": {
"pem": "-----BEGIN CERTIFICATE-----nnnnnn-----END CERTIFICATE-----\n"
},
"grpcOptions": {
"ssl-target-name-override": "xyz-peer.openshift-ibpv2-test-1-0001.us-
south.containers.appdomain.cloud"
}
},
"va0414-peer.openshift-ibpv2-test-1-0001.us-south.containers.appdomain.cloud:443": {
"url": "grpcs://va0414-peer.openshift-ibpv2-test-1-0001.us-
"tlsCACerts": {

"pem": "-----BEGIN CERTIFICATE-----nnnnnn-----END CERTIFICATE-----\n"
},
"grpcOptions": {
"ssl-target-name-override": "va0414-peer.openshift-ibpv2-test-1-0001.us-
south.containers.appdomain.cloud"
}
}
},
"certificateAuthorities": {}
}
But if the "certificateAuthorities" section is empty and client application needs to register and enroll identities with the
CA from the connection profile, then you must manually add the CA information to the generated connection profile. To get the
CA connection information, simply export the CA, from the console where it resides, to a JSON file:
1. From the nodes panel, open the CA.
2. Click the Export icon to download the CA configuration to a JSON file.
Figure 4. Click the export icon to download the CA configuration to a JSON file.
The downloaded CA JSON file resembles:
{
"display_name": "brian ca",
"api_url": "https://xyz-ca.openshift-ibpv2-test-1-0001.us-
"operations_url": "https://xyzca-operations.openshift-ibpv2-test-1-0001.us-
"type": "fabric-ca",
"ca_name": "ca",
"tlsca_name": "tlsca",
"tls_cert": "LS0tLS1...bE1UQm1OVGd",
"name": "brian ca",
"pem": "LS0tLS1...bE1UQm1OVGd",
"ca_url": "https://xyz-ca.openshift-ibpv2-test-1-0001.us-
south.containers.appdomain.cloud:443"
}
3. Open the generated connection profile that you downloaded. Edit the "certificateAuthorities": section:
$ "certificateAuthorities": {
"<CA_HOST_PORT>": {
"url": "<API_URL>",
"caName": "<CA_NAME>",
"tlsCACerts": {
"pem": ["<TLS_CERT>"]
}
}
}

Replace:
<CA_HOST_PORT> with the value of the "certificateAuthorities": from the "organizations": section of the
generated connection profile. For example, xyz-ca.openshift-ibpv2-test-1-0001.us-
south.containers.appdomain.cloud:443.
<API_URL> with the value of the "api_url" from the downloaded JSON file.
<CA_NAME> with the value of the "ca_name" from the downloaded JSON file.
<TLS_CERT> with the value of the "tls_cert" from the downloaded JSON file.
If the organization MSP was manually created by using certificates from an external CA, then there is no reason to add the CA to
the connection profile. You cannot register and enroll users with an external CA from a client application.
Updating an organization MSP definition

It is possible that you will need to update an organization MSP definition, such as the display name, or certificates that are
included inside the MSP. You can also enable Node OU support on the MSP. Enabling Node OU support is recommended
because it greatly simplifies the steps required after certificates are renewed.
Important: It is recommended that you do not change the msp_id field as this might cause breaking changes to your
network.
To update your MSP:
Export the existing MSP definition from the Organizations tab and edit the generated JSON file to modify the display
name, the existing certificates, or add new certificates.
Click your MSP definition in the Organizations tab to open it and then click theSettings icon.
If the MSP was created in this console and Node OU support is not enabled, theNode OU checkbox is selected because
you have the opportunity to enable the support now. If you only want to enable Node OU support on the MSP, you do not
need to add a new JSON file, you can go ahead and click Update MSP definition now. This action inserts the
"fabric_node_ous": section into the JSON along with the appropriate certificates for the organization. Be aware that this
action also updates the organization admin certificates on the nodes configured with this MSP definition and each node is
restarted to reflect the update.
(Optional) If you made updates to the MSP JSON definition, click Add file to upload the new JSON file.
Click Update MSP definition.
It is very important to re-export this MSP now and share it with all of the members of the consortium so they can import it
into their console and ensure they are using the latest copy of the MSP definition and certificates.
If you need to add a new admin certificate to an existing organization MSP definition, refer to the topic on managing certificates.
Manually building an MSP JSON file

This option is for advanced users only who are familiar with how certificates are used in blockchain identity management.
If you prefer to use certificates for your peer or ordering service from anexternal CA, one that is not hosted by IBM, you need to
build an MSP definition JSON file that represents the peer or ordering service organization MSP definition.
Important: Note that all certificates must be encoded in base64 format.
You can convert the contents of your certificate file, <cert.pem> from PEM format into a base64 string by running the following

Create a JSON file by using the following format:
{
"type": "msp",
"admins": [
"<admins>"
],
"root_certs": [
"<root_certs>"
],
"tls_root_certs": [
"<tls_root_certs>"
],
"enable": true,
},
},
},
}
},
}
provide either a CA root certificate or an intermediate CA certificate. You can also provide both.
admins: Paste in the signing certificate of the organization admin in base64 format.
root_certs.
host_url: Specify the URL of the blockchain console where this MSP will collect signatures.
fabric_node_OUs: Fabric-specific OUs that enable identity classification. NodeOUs contain information for how to
distinguish clients, peers, and orderers based on their OU. If the check is enforced, by setting Enabled to true, the MSP
considers an identity valid only if it is an identity of type client, a peer, an admin, or an orderer. An identity should have
only one of these special OUs, which are assigned to an identity when it is registered with the CA. See this topic for an
example of how to specify the fabric_node_OU in an MSP in the Fabric Service Discovery documentation. Or learn more
about using Node OUs in Fabric.

For example, your JSON file would look similar to:
{
"name": "org1msp",
"type": "msp",
"admins": [
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUIzRENDQVlPZ0F3SUJBZ0lVRklDZjhkbFZPbEowazJ1V0RjbEh0MzFJbk1F
d0NnWUlLb1pJemowRUF3SXcKV2pFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ
1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVFzd0NRWURWUVFERXdKallUQWVGdzB5Ck1EQT
FNVGt5TVRBNE1EQmFGdzB5TVRBMU1Ua3lNVEV6TURCYU1DRXhEekFOQmdOVkJBc1RCbU5zYVdWdWRERU8KTUF3R0ExVUVBeE1GWVd
SdGFXNHdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBVFhRc3puMzVVdwpNaDl3ZHNVSTgwNWo0T2cvdUo0OXBza3VD
U3RhNXI0R3NaSlNMYW1jdzlZY0RXcDRNMnVkbzFFdzQzQXAwbjgvCksxOHg3MTd4c3J3RW8yQXdYakFPQmdOVkhROEJBZjhFQkFNQ
0I0QXdEQVlEVlIwVEFRSC9CQUl3QURBZEJnTlYKSFE0RUZnUVUxQ3cwUDdlNk13aDh6T1k1NmdnaE9zbVNyd2d3SHdZRFZSMGpCQm
d3Rm9BVWwvNkpmck0xVXRjbQp6cFJzRTFNWEVieVovcVF3Q2dZSUtvWkl6ajBFQXdJRFJ3QXdSQUlnRWs3aEJMQ21pZDlZSGpzTk5
QSFdlZFF2Cm5tU1hsS3VWUWQ4b3kwc3pLaFlDSUdjY083R0JBWVVFL1BaaUw4Unk4QTRPL3RCZVlQN1J5WENxZU44ZmE1T1gKLS0t
LS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo="
],
"root_certs": [
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNDVENDQWErZ0F3SUJBZ0lVZityblZxMG93WXBIemhXQzBudEJVTnJhS1NJ
FNVGt4T0RJMU1EQmFGdzB6TlRBMU1UWXhPREkxTURCYU1Gb3hDekFKQmdOVkJBWVRBbFZUTVJjd0ZRWUQKVlFRSUV3NU9iM0owYUN
CRFlYSnZiR2x1WVRFVU1CSUdBMVVFQ2hNTFNIbHdaWEpzWldSblpYSXhEekFOQmdOVgpCQXNUQmtaaFluSnBZekVMTUFrR0ExVUVB
eE1DWTJFd1dUQVRCZ2NxaGtqT1BRSUJCZ2dxaGtqT1BRTUJCd05DCkFBU3VWQ0tqUk5nWndpanZoWjJiMStxZjZjbmE5ZWxrazFFb
Gl4akVXQ0l2bE9jZFUyOUpYNFdzTGcwOXdaa0EKUmdmL2tRZVpLMXdxbWRuV2xxYTl6L1VkbzFNd1VUQU9CZ05WSFE4QkFmOEVCQU
1DQVFZd0R3WURWUjBUQVFILwpCQVV3QXdFQi96QWRCZ05WSFE0RUZnUVVsLzZKZnJNMVV0Y216cFJzRTFNWEVieVovcVF3RHdZRFZ
SMFJCQWd3CkJvY0Vmd0FBQVRBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlFQXZEcVhkN3JjSnV2TDBPcGZvZ0lRVmpZMDVoTHgKSno2
NzVOYjhUc2VFc2NFQ0lBUWZpeHFxVmpVUU1hNnh5Qld1QUNXOHUzQjdzNlhNYnNKTUVKVFVoSE1PCi0tLS0tRU5EIENFUlRJRklDQ
VRFLS0tLS0K"
],
"tls_root_certs": [
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUIvakNDQWFTZ0F3SUJBZ0lVUjY0d3MrbEkwVndjR3IxdWY0RDF2K3ZXc2gw
d0NnWUlLb1pJemowRUF3SXcKWFRFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ
1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVE0d0RBWURWUVFERXdWMGJITmpZVEFlCkZ3MH
lNREExTVRreE9ESTFNREJhRncwek5UQTFNVFl4T0RJMU1EQmFNRjB4Q3pBSkJnTlZCQVlUQWxWVE1SY3cKRlFZRFZRUUlFdzVPYjN
KMGFDQkRZWEp2YkdsdVlURVVNQklHQTFVRUNoTUxTSGx3WlhKc1pXUm5aWEl4RHpBTgpCZ05WQkFzVEJrWmhZbkpwWXpFT01Bd0dB
MVVFQXhNRmRHeHpZMkV3V1RBVEJnY3Foa2pPUFFJQkJnZ3Foa2pPClBRTUJCd05DQUFSdHpyOFRpMlh5WENSc1ljbXFPVW5GSDdnV
UpnWFBSS3dpUjBVN2N4eHJoU2lYcTh1UTJpanIKRkdhMk95SVhtUVJBbmZUMElIaW5iS29qMmlJL00vc3dvMEl3UURBT0JnTlZIUT
hCQWY4RUJBTUNBUVl3RHdZRApWUjBUQVFIL0JBVXdBd0VCL3pBZEJnTlZIUTRFRmdRVXFyNDN6dWRjVUpOeVF0TkNOSlIvMGdUdnR
Jd3dDZ1lJCktvWkl6ajBFQXdJRFNBQXdSUUloQU9hSTBKbVkvNW1Cb080ZTM3QWUrNkxyTXRzR3NqdERXakNnZk5aNzVRRCsKQWlC
UmdDSDA3RVJlUkMrRGhlN3BLUkdCVlUvenhvYkZqNlV2cjgzUU1RZUJ3Zz09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
],
"certificate":

VRFLS0tLS0K",
},
"certificate":
VRFLS0tLS0K",
},
"enable": true,
"certificate":
VRFLS0tLS0K",
},
"certificate":
VRFLS0tLS0K",
}
},
"host_url": "https://ibpconsole-console.0defdaa0c51bd4a224eab4bf04a1-0000.us-
}
Save this definition as your MSP definition JSON file.
You have constructed an MSP definition, which defines the organization for your peer or ordering service nodes, and uses
certificates from an external CA. You can now return to the instructions that describe How to use certificates from an external
CA with your peer or ordering node.

Importing an MSP
Only the orderer admin can add new organizations to the consortium. If you are the orderer admin, you will need to collect the
MSP definitions of all the organizations who have been invited to the consortium and import the MSPs into the console. You can
then add the MSPs to the ordering service, by using the orderer node.
After an administrator creates an MSP definition, they can use the Organizations tab to download the MSP in JSON format to
their local file system. They can then send you the MSP JSON file in an out of band operation. Navigate to the Organizations tab
and use Import MSP Definition to import the MSP file into your console. Once an MSP definition is visible in theAvailable
organizations section, you can then navigate to your orderer node to add the organization to the consortium.
Adding an organization to a consortium

The consortium of organizations is hosted by the ordering service.
If you are the administrator of the ordering service, you can use the console to add an organization to the consortium. Navigate
to the Nodes tab and click the ordering service. On the ordering service panel, underConsortium members, click Add
organization. A side panel opens where you can select from the list of available MSP definitions that you imported into your
organizations tab. You can also use the Upload JSON option to import the MSP definition file created by another org directly.
Creating and editing a channel

After an organization is added to the consortium, the organization can use the ordering service to create a new channel or can be
added to an existing channel. The information that allows you to participate in a channel, such as joining your peers to the
channel, instantiating smart contracts, and submitting transactions, is provided by using the MSP definitions.
After your organization is added to a consortium, you can create a channel by using the following steps:
1. Import the ordering service that hosts the consortium into your console. You do not need to be an administrator of the
ordering service; but you need to provide the ordering node name and endpoint information in your console.
2. Import the MSPs of organizations that you want to add to the new channel into your console in theOrganizations tab.
Note that organizations need to be added to the consortium before they can be added to a channel.
3. Navigate to the Channels tab and click Create channel. This opens a side panel that allows you to specify the channel
name, membership, and channel policies. You can add any organizations that were added to the consortium to the new
channel.
For more information about these steps, see creating a channel in the Build a network tutorial.
Updating an MSP in a channel definition

Over time you might need to update the certificates in an MSP definition that is already associated with a channel. When that
situation occurs follow these steps to update an organization's MSP definition in the channel:
1. Navigate to the Channels tab in your console.

2. Click the channel that contains the organization MSP that you want to update and open it.
3. Click the Channel details tab.
4. Click the associated channel member's tile that you want to update.
5. If you have not already imported the updated MSP definition into the console, you can upload the file here.Note: This
action will not update the associated MSP definition in the Organizations tab. If you have already updated the MSP
definition in the Organizations tab of the console, you can select it from the drop-down list.
Removing an organization
If you want to stop using an instance of the IBM Blockchain Platform, you need to remove your organization from the blockchain
network before you delete your service instance. This ensures that the removed organization is not affecting the governance of

the network after it has left the network. You can remove your organization by using the following steps:
1. Remove your organization from channels that you joined. You need to update the endorsement policy of the smart
contracts that are deployed on the channel to remove your organization from the policy. If you do not update the
endorsement policy, your organization might be required to endorse transactions after you have left the channel, causing
transactions to fail.
You can then update to the channel to remove your organization from the list of channel members. Navigate to the Channels
tab and click the Settings icon. You can use the Organizations section to remove your organization from the channel. The
channel update policy is updated to remove your organization automatically. When you are ready, click Update channel to
submit a channel update request. The request starts the process for collecting the signatures that are required to update
the channel, depending on your update policy.
After you remove your organization from the channel, you can delete your peers on the IBM Blockchain Platform. If
transactions can be successfully submitted to the network after you remove your peers, your organization is no longer
required to endorse transactions.
2. Have your organization removed from the consortium hosted by the ordering service. After you are removed from the
consortium, your organization can no longer be added to new channels. This action needs to be completed by an ordering
service administrator.
Navigate to the Nodes tab and click the ordering service of your network. On the ordering service panel, find the organization
to be removed in the list of Consortium members. Click the Delete button in the corner of the organization MSP definition
tile.
3. Delete your ordering nodes. If you operate ordering nodes that are part of a multi-node ordering service, you need to
remove your ordering nodes from the network before you remove your ordering organization. Your ordering nodes need to
be removed from the consenter set of each channel before they are removed from the ordering service.
Navigate to the Channels tab and click the Settings icon to update the channel. You can use the Consenter Set section to
remove your ordering node from the channel. When you are ready, click Update channel to submit the channel update
request. The update request starts the process for collecting the signatures that are required to update the channel,
depending on the channel update policy. After you have you removed your ordering nodes, you can use the Ordering
service administrators section to remove your organization from the set of orderer administrators.
After you remove your ordering nodes from the consenter set of each channel, you can remove your nodes from the ordering
service. Navigate to the Nodes tab and click the ordering service of your network. On theOrdering service panel, click the
Ordering nodes tab. Click your ordering node and then click Delete. Because Raft consensus requires that a majority of
ordering nodes are up to maintain a quorum, you need to remove one ordering node at a time. After you have deleted your
ordering nodes, you can remove your organization from the set of ordering service administrators. Find your organization
MSP definition on the list of Orderer administrators and click the Delete icon in the corner of the organization definition
tile.
After you complete these steps, your organization will no longer affect the governance of the network. You can safely delete your
service instance of the IBM Blockchain Platform.
Managing certificates
IBM® Blockchain Platform is based on Hyperledger Fabric and builds permissioned blockchain networks. Participants are known
as members of the network, and their activities and access to network resources are verified continuously. Learn how to manage
a member's identity in the form of a trusted x509 digital certificate.
Target audience: This advanced topic is designed for system administrators or operators who are responsible for registering

users, enrolling identities, and administering ordering services or channels. You should be familiar with Membership Service
Providers (MSPs) and how they are created.
IBM Blockchain Platform manages most of the certificate operations without users needing to handle their certificates. However,
there are instances when you need to manage the certificates that allow you to communicate with the network, such as for
developing applications or renewing certificates before they expire. This topic is a short guide to your Certificate Authority and
the underlying certificate infrastructure. This information can help you understand the certificates that you will be working with
and the tasks you are responsible for.
For details on Hyperledger Fabric certificates, including certificate names, types, and locations, see the Certificates
Management Guide.

Certificate authorities (CAs) provide identity on the network. A CA can be considered as a publicly trusted notary that acts as an
anchor of trust among multiple parties. All entities in the network are given a certificate that is signed by a root CA that
encapsulates their digital identity. This certificate is the root of trust for all of the sign and verify operations that are performed
on the network. For more details about how certificate authorities are used to establish identity, see Hyperledger Fabric
documentation.
Each organization in the network has their own CA. Your organization CA signs requests for all of the entities and components
that you own, such as your admin, peers, or applications. If you want to add a node or new application to your network, you need
to register the new user with your Certificate Authority (registration). Then, via the enrollment process, the CA generates a public
and private key pair. The "enrollment certificate", also known as the signed certificate or public key, is shared with the network.
Overview
The following diagram shows all of the certificates that need to be managed and where they reside on your network.
Figure 1. Certificate overview diagram
The left column includes the certificates for the blockchain CA, peer, and ordering nodes. There are two certificates that are
included on the CA node, the CA root certificate and the CA TLS cert. The root certificate is included here for completeness, but

because it expires in 15 years, update instructions are not provided. The peer and ordering nodes are similar in that they both
contain an enrollment certificate (the public key or signed certificate), their TLS certificate that enables them to transact with
other nodes in their organization, and their MSP admin certificate, which represents the admin identity that is allowed to
administer the node.
The IBM Blockchain Platform can automatically renew the enrollment certs for the peer and ordering nodes and the TLS
certificate for the peer. But the MSP admin identities have to be manually renewed. If the MSP is enabled for Node
Organizational Units (Node OUs), no further action is required. More information about Node OU support and how to determine
whether the MSP is enabled for it is provided in this topic.
The right column shows the certificates that are relevant to the system channel and the application channel. When the MSP is
not enabled for Node OU support, additional steps are required to update these certificates on the system and application
channels and are provided here.
Important: Because the certificate renewal process is different for peers and ordering nodes, the certificate renewal
tooling described in this topic cannot be used on networks where the peers and ordering nodes share the same
organization MSP definition.
Node OU support
When you register a user with the CA, you need to select a user Type of client , peer , orderer , or admin , that is used to
confer a "role" onto the identity. Roles are referred to as Organizational Units (OU) inside a certificate and MSPs can be
configured to recognize these roles. The admin and orderer types were added to the IBM Blockchain Platform when Fabric
v1.4.3 was included and contains support for Node OUs in MSPs and channels.
This new capability means that when the MSP admin identity is enrolled during MSP creation, the generated signed certificate
includes the admin type as an OU inside the certificate. This admin designation means that the signed cert of the identity does
not need to be included in the MSP defining the organization. You can learn more about the benefits of Node OUs in the Fabric
documentation on the Membership Service Provider.
Because this functionality was not yet available when the IBM Blockchain Platform service was initially offered, all MSP admin
identities that were enrolled before Node OU support was added to the platform in December 2019, do not contain the admin
OU in their signed certificate. Instead, when the MSP was created, the signed cert, or certificate, for the MSP admin was placed
in the admins section. The platform supports both patterns, but if the Node OU configuration was not enabled when the
organization MSP was created, additional steps are required after certificate renewal to update the MSP and any channels that
the MSP is part of. Therefore, if your MSPs currently are not configured with Node OU support, it is recommended that you add
Node OU support now, to avoid the extra updates steps that are required in one year when the certificates expire again.
Note: If your certificates have already expired, you are not able to complete these steps, but should come back and do
this after you renew the certificates.
Prerequisite: Before you can take advantage of Node OU support, ensure that your CAs are at Fabric v1.4.3 or higher. Open the
CA tile to view the Fabric version. If the CA is not at v1.4.3 or higher, you should upgrade it now.

Figure 2. View CA Fabric version
Enabling Node OU support for an MSP definition is a two-part process. First, you have to update the MSP definition itself, then
you have to update the same MSP definition on the channel.
Part one: Enable Node OU support for an MSP definition

1. Open the Organizations tab to view the Node OU status for each MSP:
Figure 3. View Node OU status on MSP tile
2. Click the Settings icon for the MSP. The checkbox to add Node OU is selected by default. You do not have to add a new
JSON file, you can simply click Update MSP definition to enable Node OU support for the MSP.
Figure 4. Node OU checkbox
The MSP is also automatically updated on any peer or ordering nodes that are configured to use this MSP. There is a brief
downtime when the node is automatically restarted to use the updated MSP.
Part two: Enable Node OU support for the MSP on a channel

1. Open the Channels tab, select the channel that you want to update and clickChannel details.
2. Scroll down and click the channel member MSP definition that you just enabled Node OU support for. The checkbox to
enable Node OU support is selected by default.

3. Select the existing MSP definition and the associated identity and clickUpdate MSP definition.
Important: Because you likely still have admin certificates in the MSP that will expire, you still need to follow the manual
steps in this topic to update them. But after you complete that process, you do not have to follow the manual steps again
next year after the certificates expire, since you have now enabled the Node OU support on the MSP.

By default, most certificates that are generated by IBM Blockchain Platform CAs expire after one year. However, the CA root
certificate, CA TLS certificate, and the ordering node TLS certificates have longer periods before expiration. The default
expiration period is the same for certificates that are generated by using the Fabric SDKs, the Fabric CA client, or by using the
console. The expiration date for all certificates that expire within five years is visible in the console, and how to view the actual
date is described later in this topic.
Automatic certificate renewal

Use the following topics to set up automatic certificate renewal.
Enrollment and TLS certificates

Because the console automatically enrolls identities for peer or ordering nodes when the nodes are deployed, the IBM
Blockchain Platform automatically renews the enrollment (signing) certificates for the peer and ordering nodes and the peer
TLS certificate. If the certificates expire within 30 days, the platform automatically attempts to contact the CA and renew the
certificates. After these certificates are automatically renewed, there is no further action that needs to be taken.
If the CA is offline, unreachable, or the CA TLS certificate has expired, the certificates cannot be automatically renewed. The peer
or ordering node displays a warning message indicating that certificate expiration is approaching or has occurred and you need
to take action.
Peer and ordering node enrollment certificates can be renewed from the console, by opening the node tile and clicking the
Settings icon. Click Update certificates to renew either the enrollment or TLS certificate. See detailed instructions for the peer
and ordering node enrollment and TLS certificates. Note that when a certificate is updated, the node is restarted.
Admin certificates
Organization MSP admin certificates cannot be automatically renewed. Instead, you need to follow the manual certificate
renewal process, included in this topic, to update these certificates. If you have a large number of channels on your network,
Ansible playbooks, also described later in this topic, are available to update admin certificates that have not yet expired across
the channels on your network in a bulk action.
Certificate types and actions

When certificates expire, nodes can no longer process transactions and your applications can no longer interact with your
network. Therefore, before a certificate expires, you need to enroll the identity again to generate a new certificate, a process
referred to as "certificate renewal".
The following tables describe the types of certificates that you need to manage, how to view their expiration date, and how to
maintain them.
CA TLS certificate

Certificate Description How Default How to How to Impact if What to do
generated expiration view renew expires if expired
expiration
CA TLS Used to trust the Generated 2.5.x: 10 If it See Transactions See

certificate CA server. when the years 1 expires Renew continue. Renew
Contains the CA is first within five the CA the CA
public key that started 2.1.x: 1 years, the TLS - Cannot TLS
must be shared because year expiration certificate. register or certificate.
with all TLS is date is enroll new
members in the enabled. visible identities,
organization that from the but
want to transact console. transaction
with any node in Open CA traffic does
the organization. node and not stop.
When any client view TLS
or node submits Cert - Automatic
a transaction to Expiration certificate
another node, it field 2 renewal
must include fails.
this certificate as
part of the - Cannot
transaction to renew other
prevent “man in certificates
the middle” without
attacks. fixing CA
TLS
certificate
first.
Table 1. How to manage the CA certificates
Peer certificates
Certificate Description How Default How to view How to Impact if What to do
generated expiration expiration renew expires if expired
Peer The public key Generated 1 year Open Automatic Production Manually
enrollment that is used to when the console renewal is outage update the
certificate verify that the peer is peer node attempted peer
(signcert) signatures that deployed and view 30 days Peers can certificates.
nodes attach to based on Enrollment before no longer
communications the peer Cert expiration. connect to
were generated enroll ID Expiration orderers or
by the node's and secret field. If to each
private key. that is automatic other.
provided. renewal
fails,
manually
update the
peer
certificates.
Peer TLS When TLS is Generated 2.5.x: 15 Open Automatic Production Manually
certificate enabled on a when the years 3 console renewal is outage update the
(signcert) network, each peer is peer node attempted peer
node must deployed. 2.1.x: 1 and view 30 days SDK does certificates.
register a user year TLS Cert before not allow
and enroll an Expiration expiration. connection
identity with the field. when TLS
TLS CA. This is If certificates
the TLS automatic are
certificate for renewal expired.
the peer from fails,
that process and manually
is required for update the
the peer to start. peer
certificates.
Table 2. How to manage the peer certificates
Orderer certificates

Certificate Description How Default How to view How to Impact if What to do
generated expiration expiration renew expires if expired
Orderer The public key Generated 1 year Open Automatic Production Manual
enrollment that the when the console renewal is outage certificate
certificate orderer uses to ordering ordering attempted renewal
(signcert) sign node is node and 30 days Orderers
transactions. deployed view before can no
based on Enrollment expiration. longer work.
the Cert
ordering Expiration If
service field. automatic
enroll ID renewal
and secret fails, see
that is Manual
provided. certificate
renewal
Orderer When TLS is Generated 2.5.x: 15 Open Automatic Production Manual

TLS enabled on a when the years 4 console renewal is outage certificate
certificate network, each ordering ordering attempted renewal
(signcert) node must node is 2.1.x: 1 node and 30 days Ordering
register a user deployed. year view TLS before nodes are
and enroll an Cert expiration. no longer
identity with Expiration allowed to
the TLS CA. field. If participate
This is the TLS automatic in cluster.
certificate for renewal Quorum is
the ordering fails, see lost,
node from that Manual environment
process and is certificate goes down.
required for renewal
the ordering
node to start.
Table 3. How to manage the orderer certificates
Peer admin certificate

The following diagram summarizes the process for updating peer admin certificates on your network. Click a circle to view the
instructions.
Certificate Description How Default How to view How to Update Update Update
generated Expiration expiration renew MSP node admin channel

Peer The admin Generated 1 year Wallet tab: Enroll No action No action No action
organization certificate when you Click the new is required is required is required
admin that is used create the peer identity when when when
certificate to peer organization Node OU Node OU Node OU
administer organization admin is enabled is enabled is enabled
the peer MSP and identity tile for the for the for the
and install provide the to view the MSP. MSP. MSP.
smart admin expiration
contracts identity enroll date of the Otherwise, Otherwise, Otherwise,
on the peer. ID and secret. certificate Append Associate Update
It can also In addition to and private the admin new channel
be being part of key. certificate admin
configured the peer node to the MSP identity on or
to manage configuration, Peer node: definition. peer.
the this MSP If Node OU Bulk
application certificate support is admin
channel can also be not enabled certificate
that the included in for the peer update
peer the channel MSP, open with
belongs to. that the peer peer tile Ansible
The joins as a and view playbooks
associated channel the Admin
admin user member or Cert
is channel Expiration
registered administrator. in the left
with the column.
organization
CA before MSP tab:
the peer Open peer
and organization
organization MSP tile,
MSP are the admin
created. certificate
expiration
date is
listed in left
column.
Channel
details tab:
Open
channel and
click
member tile
to view
expiration
date.
Table 4. How to manage the peer organization admin certificate
Ordering service MSP admin certificate

The following diagram summarizes the process for updating orderer organization admin certificates on your network. Click a
circle to view the instructions.

Certificate Description How Default How to view How to Update Update Update
generated expiration expiration renew MSP node admin system
channel
Ordering The admin Generated 1 year Wallet tab: Enroll No action No action No action
service certificate when you Click the new is required is required is required
organization that is used create the ordering identity when when when
admin to organization service Node OU Node OU Node OU
certificate administer MSP and admin is enabled is enabled is enabled
the ordering provide the identity tile for the for the for the
service and admin to view the MSP. MSP. MSP.
submit or identity enroll expiration
approve ID and date of the Otherwise, Otherwise, Otherwise,
channel secret. In certificate Append Associate Update
updates. addition to and private the admin new ordering
The being part of key. certificate admin service
associated the ordering to the MSP identity on admin
admin service MSP tab: definition. orderer
identity is configuration, Open the or
enrolled this MSP ordering
with the certificate service Bulk
organization can also be organization admin
CA before included in MSP tile certificate
the node the ordering and the update
and service admin with
organization channels. certificate Ansible
MSP are expiration playbooks
created. date is
listed in left
column.
Table 5. How to manage the orderer organization admin certificate
Manual certificate renewal

While the platform automatically renews the certificates for peer and ordering nodes if the associated CA is available, customers
are responsible for managing certificate expiration and renewal of the following certificates:
CA TLS certificate
Peer and ordering node enrollment and TLS certificates, only when automatic renewal is not successful
MSP admin certificates
Certificates from an external CA.
If the admin certificates have been stored or imported into the console wallet, you can monitor the exact date of expiration for
each identity. Click an admin identity tile to view the expiration date of the certificate and private key.

Figure 5. Admin identity certificate expiration
Otherwise, if certificates expire within five years, their expiration date is visible from the peer, ordering node, MSP, and channel
tiles.
To manually renew certificates, see:
CA TLS certificate
Peer enrollment and TLS Certificates
Ordering node enrollment and TLS certificates
MSP Admin certificate
Certificates from an external CA
Renew the CA TLS certificate

Because automatic renewal of peer and ordering node enrollment certificates is not possible when the CA TLS certificate
expires, it is important to keep your CA TLS certificate current. Transactions on the network can continue to be successfully
processed even if the CA TLS certificate expires, but you are not able to enroll new identities, which is required when certificates
expire.
The process to renew the CA TLS certificate is same regardless of whether it has expired or not, although it is not available on an
imported CA. In that case, the update needs to be performed from the console where the CA was deployed.
1. Open the CA tile and click the Settings icon.

2. Click Renew TLS certificate. The certificate is replaced and the CA is restarted.
3. After the CA is restarted, click the Refresh certificates icon next to the CA Settings icon to update the console.
4. For your network to work, it is required that you update all of the associated nodes that are currently using the original TLS
certificate with the new TLS certificate to secure their communications. Click the Settings icon again and this time click
Update associated nodes. All of the nodes in the list of associated nodes need to be updated.
Important: This update requires a brief restart of the associated nodes. For zero downtime and to ensure nodes are still
available to process transactions, it is recommended that the updates are performed on one node at a time.
Tip: Because the console only shows CA TLS certificate expiration dates if they are within five years, it is possible that the

expiration date of the CA TLS certificate is not visible when you open the CA tile. If you've just successfully renewed the
certificate, the expiration date is no longer visible on the page.
Renew Peer enrollment and TLS Certificates

When the peer enrollment certificate expires, the peer can no longer communicate with orderers or other peers in the
organization. Likewise, when the peer TLS certificate expires, client applications that use the Fabric SDK are no longer able to
send transaction proposals to the peer. The automatic certificate renewal process attempts to re-enroll the peer enrollment and
TLS certificates 30 days before they expire, and when successful, no further action is required on your part. But if the automatic
certificate renewal fails because the CA is down or unreachable when the renewal attempt is made, or if the associated CA TLS
certificate is expired, you have to manually update these certificates. When automatic renewal fails, a warning is displayed on
the peer tile.
While you can use the following steps to renew certificates before or after they expire, to avoid an interruption of service, it is
best to renew the certificates before they expire. Check the expiration date of your peer enrollment and TLS certificates by
opening the peer node.
Figure 6. Peer enrollment and TLS certificate expiration
1. Open the peer and click the Settings icon.

2. Click Update certificates. You can renew either the Enrollment certificate or the TLS certificate or both, based
on their expiration dates.
3. In the drop-down box for each certificate type, select Re-enroll certificate if the certificate has not expired, or Enroll
certificate if it has already expired.
4. When you click Update certificates, the peer is restarted. Verify the renewal is successful by clicking the refresh icon and
examining the updated enrollment and TLS certificate expiration dates.
Figure 7. Certificate refresh button

Note: While the console does not allow you to set custom expiration dates for certificates, notice that the Peer TLS
certificate expiration date is in 15 years, so that renewal of this TLS certificate is not required again next year. However,
the peer enrollment certificate expires again in one year, so you will need to renew it again before that date.
An alternative to renewing these certificates is to simply deploy a new peer, and then delete the peer with expired certificates.
You would need to configure the new peer on the network in the same way the existing peer is configured, namely:
Join it to the same channel or channels.

Make this peer an anchor peer, if the previous peer was an anchor peer.
Install the same smart contracts on it.
Download a new connection profile that includes the new peer for client applications to address the new peer.
Renew ordering node enrollment and TLS certificates

If any single ordering node enrollment certificate expires, the entire ordering service goes down. When the ordering node TLS
certificate expires, the node can no longer participate in the Raft cluster, which can cause consenter quorum to be lost, and the
blockchain network goes down. It’s also not possible to upgrade any node in the ordering service if one of ordering nodes in the
orderer consenter set is down. The automatic certificate renewal process attempts to re-enroll the ordering node enrollment and
TLS certificates 30 days before they expire, and when successful, no further action is required on your part. But if the automatic
certificate renewal fails because the CA is down or unreachable when the renewal attempt is made, or if the associated CA TLS
certificate is expired, you have to manually update these certificates. When automatic renewal fails, a warning is displayed on
the ordering node tile. While you can use this process to renew certificates before or after they expire, to avoid an interruption of
service, it is best to renew the certificates before they expire. Check the expiration date of your ordering node enrollment and
TLS certificates by opening the ordering node.
Figure 8. Ordering node enrollment and TLS certificate expiration
Important: Because this certificate renewal process restarts the ordering node, and in the case of a TLS certificate
renewal, the node can no longer participate in the application channel consenter set, you need to pay particular attention
to maintaining quorum on the application channel throughout this process. Before attempting these steps, and to avoid
any interruption of service, ensure that you still have enough ordering nodes available to maintain quorumwhile this
node is restarted or offline, in the case of a TLS certificate update.
The process to renew the enrollment certificate is the same for the ordering node as it is for the peers. But when you renew the
ordering node TLS certificate, additional steps are required. Before proceeding, if you have a single-node ordering service and

need to renew the TLS certificate, you should review Considerations for a single node ordering service.
Renew the certificates

1. Open the ordering service and click the Ordering nodes tab. As ordering node certificates approach expiration, a warning
icon is visible on their tile.
2. Open the ordering node you want to update. If automatic certificate renewal failed for the node, you should see a warning.
Click the Settings icon.
3. Click Update certificates. You can renew either the Enrollment certificate or the TLS certificate or both, based
on their expiration dates.
4. In the drop-down box for each certificate type, select Re-enroll certificate if the certificate has not expired, or Enroll
certificate if it has already expired.
5. When you click Update certificates, the ordering node is restarted. Verify renewal is successful by clicking the certificate
refresh button next to the Settings icon and examining the updated enrollment and TLS certificate expiration dates. Notice
that the ordering node TLS certificate expiration date is in 15 years, so that renewal of this TLS certificate is not required
again next year. However, the enrollment certificate expires again in one year, so you will need to renew it again before
that date.
6. If you only updated the ordering node enrollment certificate then you are done. But as mentioned earlier, if you updated
the ordering node TLS certificate, additional steps are required to update the consenter set on the ordering service system
and application channels with the new TLS certificate.
Update the consenter set on the ordering service system channel (TLS certificate renewal only)
When you update the TLS certificate, you also need to update the consenter set on the ordering service system channel. This
action ensures that any new application channels which include this ordering node as a consenter will use the updated TLS
certificate.
Note: In order to update the ordering service, you must have the ordering service organization admin identity in your
wallet.
1. Go back to the Ordering service page and scroll down to the Ordering service consenters table.
2. Click the action menu next to the URL, and click Update orderer certificates.
3. After you copy and paste the name of the ordering service consenter set, displayed at the top of the side panel, and click
Update consenter, the base-64 encoded TLS certificate is added to the consenter set of the ordering service system
channel.
Update the consenter set on the application channel (TLS certificate renewal only)
Next we have to update the TLS certificate for this ordering node on all application channels that include this ordering node as a
consenter. Until you complete these steps and enough channels members approve the generated channel update request, the
ordering node is not able to act as a consenter on the channel. Therefore, ensure there are enough other ordering nodes
available in the consenter set to maintain quorum while this node is unavailable.
Note: In order to update the application channel, you need to have the channel member admin identity in your wallet.
1. From the Channels tab, open the application channel that you need to update and click theChannel details tab.
2. Scroll down to the Ordering service consenters table and click the action menu , next to the URL and click
Update orderer certificates.
3. Copy and paste the name of the consenter set, displayed at the top of the side panel.
4. To submit this update request to the channel members, you need to select the ordering service MSP from the drop-down
list and then the associated orderer organization admin identity from your wallet. When you click Update consenter a
channel update notification is sent to the consortium members for approval.

5. After enough channel members approve this update according to the channel update policy, the ordering node can
resume participation in the consenter set.
6. Repeat these steps for every channel that includes this ordering node as a consenter.
Considerations for a single node ordering service

If you are using a single-node ordering service and need to renew the ordering node TLS certificate, additional steps are
required. The Re-enroll button for the ordering node TLS certificate is only visible when the node is running a Fabric version
greater than or equal to v1.4.9, or in the case of a Fabric v2.x node, the version must be greater than or equal to v2.2.1. Likewise,
the Enroll button is only visible when the Fabric version is greater than v1.4.9 or in the case of a Fabric v2.x image, it must be
greater than v2.2.1.
Ordering node TLS certificate not expired - If the ordering node TLS certificate has not expired, you should upgrade the
Fabric v1.4.x node to 1.4.9 or Fabric v2.x node to 2.2.1. Then use the reenroll button which is now visible in the console
and follow the normal steps to Renew ordering node enrollment and TLS certificates.
Important: To avoid problems, do not mix Fabric v1.4 and v2.x nodes in your Raft cluster. All ordering nodes should be
running v1.4.x or all should be running v2.x.
Ordering node TLS certificate expired - If the ordering node TLS certificate has expired then theEnroll button is blocked.
Open a support ticket to address the problem.
Renew MSP Admin certificate

Use the following steps to renew an MSP admin certificate.
Step one: Enroll new identity

Before an organization admin certificate expires, you must enroll the identity again to generate a new certificate and public key
by using the associated CA. These instructions assume that you have the original enroll ID and secret that was specified when
the user was originally registered. If the certificates were generated with the console, you can use the following instructions:
1. Open the CA tile. *

2. Locate the enroll ID for the identity in the table and clickEnroll identity from the action menu.
3. After you verify that you have selected the correct CA, Root Certificate Authority, or TLS Certificate Authority, according
to the type of certificate that you are renewing, provide the enroll ID and secret that was specified when the user was
initially registered. If the enroll ID and secret are not available, follow the same steps for an expired admin certificate.
4. Because the certificate and private key are never stored by the console, you must download them and store them securely
and export the identity.
5. Click Add identity to wallet. Wallet identities cannot be replaced, you need to either delete the existing wallet identity or
give this one a different name.
If the certificates were generated from the Fabric CA client or Fabric SDKs, then they need to be renewed where they were
generated. You can now use the updated certificates when you follow instructions in subsequent steps.
Tip: If you reach the enrollment limit for an identity, simply use the console to register a new user and enroll an identity
and then use the generated certificate in subsequent steps.
If the CA admin identity expires, you are not able to update any of the identities in the CA table.And when you open the CA
node, there is a message that indicates the users cannot be listed. To fix this problem, click Associated identity for root CA. In
the side panel that opens, click the Enroll ID tab to enroll a new admin identity for the CA admin by providing the originalEnroll
ID and secret and a new display name for the identity, then click Associate identity. You can now proceed with the steps to
enroll a new identity for other users in the table by clicking Enroll identity from their action menu.

Step two: Update organization MSP
If this is an MSP admin identity that was generated after Node OU support was enabled for the MSP, the admin role is inserted
directly into the generated admin certificate, and therefore the MSP does not need to be updated. You can skip this step.
If this is an MSP admin identity, and the associated MSP Node OU support was disabled when the identity was originally
enrolled, then you need to perform the following additional steps:
Important: Before attempting these steps, be aware that these actions trigger a restart of the peer or ordering nodes that
are configured with this MSP.
1. Open the Nodes tab in your console.

2. Locate the node tile that requires the admin certificate update. The MSP name is listed on the tile under the node name.
Make a note of the MSP name.
3. Open the Organizations tab.
4. Locate the MSP tile for the organization MSP from step two and click theExport icon.
5. Open the downloaded MSP JSON file in a text editor.
6. Edit the admins element by appending the new base64-encoded certificate string that you generated in the previous
section to the end of the list of comma-separated admin certificates. If the identity was enrolled from the console, ensure
that the Root Certificate Authority was selected. Open the identity JSON file that you exported, and copy the string from
the cert field.
7. Save your changes.
8. In the Organizations tab, open the MSP tile for the peer and click theSettings icon.
9. In the side panel, click Add file and select the updated MSP JSON file.
10. Notice that the Node OU checkbox is selected for you, which means that Node OU support will be enabled on the MSP
and that you will not have to repeat this process again in another year when the certificates expire. For now though, you
still need to complete all of the steps in this manual renewal process.
Figure 9. Update MSP with Node OU enabled
11. Click Update MSP definition. All Peer and ordering nodes in this console that include this MSP as their node admin are
automatically updated with the new MSP and restarted.
12. Export this updated MSP, and in an out of band action, share the file with all of the members of the network who must
import it into their console. It is important for them to import the updated MSP, so when they create a new channel, they
are using the MSP definition with the latest admin certificate.
To verify that the update worked, open the MSP tile and view the updated expiration date.
Step three: Associate new admin identity on peer or ordering service

If the updated certificate is an admin certificate for a peer or ordering service, you need to update the node admin identity. Open
the associated peer or ordering service and click the Associate identity for peer or Associate identity for ordering service and
browse to the newly created identity from the wallet.
Tip: To verify that this update worked successfully on the peer, after you associate the identity, you should be able to see
the list of channels that the peer is on and list the smart contracts that are installed on the peer.

Step four: Update peer organization MSP on application channel
Important: As with all application channel updates, this update needs to be performed by a channel operator and the
change will follow the channel update approval process according to the policy that was configured when the channel was
created.
If the peer organization MSP was not originally created with the Node OU configuration enabled, you also need to update all
application channels that include the MSP so that it uses the new admin certificate. When the Node OU configuration is enabled,
the MSP uses the value of the OU inside the certificate to determine if the identity is an admin in addition to checking the admin
section of the MSP definition.
Complete the following steps for a peer admin certificate:
1. Open the channel to be updated in the console.

2. Click Channel details and scroll down to Channel members.
3. Click the channel member that you want to update.
4. On the Update MSP definition panel, select the updated MSP and the original identity and click Update MSP definition.
You must use the original identity for this step because it's currently the only one with permission to make channel
updates. This action replaces the existing peer organization admin MSP definition with the updated MSP that includes the
new admin certificate. Now this channel has the newest organization admin certificate.
Step five: Update channel member on ordering service system channel

If this is a peer admin MSP that is an ordering service consortium member, the ordering service admin needs to update the
ordering service system channel. Because the ordering service system channel serves as a template for new application
channels, taking this action keeps it current as the associated MSPs are updated. Before attempting these steps, the ordering
service admin should have already imported the updated MSP from step two into their console.
1. From the Nodes tab, the ordering service admin opens the ordering service tile.
2. Delete the existing consortium member that contains the original MSP definition, and then add the consortium again with
the new admin certificate by clicking Add organization. Browse to the new MSP JSON file from step two.
Figure 10. Ordering service admin MSP update
Step six: Update ordering service admin on ordering service system channel
If the updated certificate is for the ordering service MSP admin, you need to update the ordering service.
1. From the Nodes tab, open the ordering service tile.

2. Under Ordering service administrators click the Settings icon on the ordering service organization MSP tile.

Figure 11. Ordering service admin MSP update
3. From the Existing MSP ID tab, select the MSP that needs to be updated and then select theoriginal identity to sign the
request. You must use the original identity for this step because it's the only one with permission to make channel
updates. This action replaces the existing MSP definition for the ordering service admin with the updated MSP with the
new admin certificate.
Step seven: Update orderer organization MSP on channel
Important: Similar to step four, this update needs to be performed by a channel operator and the change will follow the
channel update approval process according to the policy that was configured when the channel was created.
If the orderer organization MSP was not originally created with the Node OU configuration enabled, you also need to update all
application channels that include the MSP so that it will use the new admin certificate. When the Node OU configuration is
enabled, the MSP uses the value of the OU inside the certificate to determine if the identity is an admin in addition to checking
the admin section of the MSP definition.
Complete the following steps for an orderer organization admin certificate:
Orderer organization admin identities cannot update an application channel. Therefore, a consortium member needs to import
the updated orderer organization admin MSP into their console and then complete the following steps:
1. Open the application channel to be updated in the console.

2. Click Channel details and scroll down to Orderer members.
3. Click the orderer member that you want to update.
4. On the Update MSP definition panel, select the updated MSP and click Update MSP definition. An update notification
request is generated.
5. The orderer organization admin needs to approve the request and submit it to the channel.

Some customers prefer to use a third-party, or "external" CA to generate their peer and ordering node enrollment and TLS
certificates, as well as the organization admin certificates. But, similar to certificates generated by a Fabric CA, they do expire,
and their expiration date needs to be monitored to avoid a network outage caused by their expiry. And like certificates generated
by a Fabric CA, expiration dates of certificates from an external CA are visible throughout the console. Before the certificates
expire you need to request new certificates from your certificate provider, and then use the console to update them across your
network. The process to update them using the console depends on the certificate type.
Peer and ordering node enrollment and TLS certificates

If the certificates are for peer or ordering node enrollment or TLS certificates, they can be updated by completing the following

steps:
1. Open the peer or ordering node tile and click theSettings icon and then Update certificates:
Figure 12. How to update certificates from an external CA
2. Click Add certificate and browse to the updated certificate .pem files. You do not have to replace all of them, but if you
provide an enrollment certificate, you also need to provide the associated key file. And likewise, if you provide a TLS
certificate you also need to provide the associated key.
3. When you click Update certificates, the peer or ordering node is restarted. Verify the renewal is successful by examining
the updated enrollment and TLS certificate expiration dates.
If you updated the ordering node TLS certificate, the following additional steps are required:
Update the consenter set on the ordering service system channel (TLS certificate renewal only)
When you update the TLS certificate, you also need to update the consenter set on the ordering service system channel. This
action ensures that any new application channels which include this ordering node as a consenter will use the updated TLS
certificate.
Note: In order to update the ordering service, you must have the ordering service organization admin identity in your
wallet.
1. Go back to the Ordering service page and scroll down to the Ordering service consenters table.
2. Click the action menu next to the URL, and click Update orderer certificates.
3. After you copy and paste the name of the ordering service consenter set, displayed at the top of the side panel, and click
Update consenter, the base-64 encoded TLS certificate is added to the consenter set of the ordering service system
channel.
Update the consenter set on the application channel (TLS certificate renewal only)
Next we have to update the TLS certificate for this ordering node on all application channels that include this ordering node as a
consenter. Until you complete these steps and enough channels members approve the generated channel update request, the
ordering node is not able to act as a consenter on the channel. Therefore, ensure there are enough other ordering nodes
available in the consenter set to maintain quorum while this node is unavailable.
Note: In order to update the application channel, you need to have the channel member admin identity in your wallet.

1. From the Channels tab, open the application channel that you need to update and click theChannel details tab.
2. Scroll down to the Ordering service consenters table and click the action menu , next to the URL and click
Update orderer certificates.
3. Copy and paste the name of the consenter set, displayed at the top of the side panel.
4. To submit this update request to the channel members, you need to select the ordering service MSP from the drop-down
list and then the associated orderer organization admin identity from your wallet. When you click Update consenter a
channel update notification is sent to the consortium members for approval.
5. After enough channel members approve this update according to the channel update policy, the ordering node can
resume participation in the consenter set.
6. Repeat these steps for every channel that includes this ordering node as a consenter.
Peer and ordering node organization admin certificates

When organization admin certificates are generated by an external CA, these certificates are manually added to the organization
MSP JSON file. And when they are updated, the certificate inside the JSON file also needs to be updated. Certificate expiration
dates depend on the certificate provider but are also visible from the MSP tile in the Organizations tab. Follow the same
processes that are described in steps 2 - 7 to update the admin certificate in the MSP, peer, orderer, and channel. If any of the
channel member or channel orderer organization admin certs have expired, then you also need to override the orderer
configuration to allow expired certs for channel updates.
Bulk admin certificate renewal with Ansible playbooks

If your network contains a large number of channels that need to be updated, or if you prefer to automate the process of
updating the peer organization MSP or orderer organization MSP on the ordering service, system channel, and application
channel, a set of Ansible playbooks is available to script this process. These playbooks can only be used if the certificates have
not expired. See the playbooks under Adding an administrator certificate for instructions.
Expired certificates
When certificates expire, it is likely that peer, orderer, and channel operations will fail, but it is still possible to update the
certificates. The process to address them depends on whether they are MSP admin certificates or enrollment certificates.
How to fix expired organization admin certificates

If the peer or orderer organization admin certificates have expired, you need to generate certificates for a new admin identity.
The overall process depends on whether Node OU is enabled for the MSP that the admin certificate belongs to.
Register a new user and enroll the identity for a new peer organization or orderer organization admin identity with the same CA
that the existing peer or orderer organization admin was registered with.
1. Open the peer or orderer organization CA.

2. Click Register user and specify a new enroll ID and secret.
3. Select a Type of admin.
4. Configure the rest of the settings as you did for the original admin identity and clickRegister user.
5. Right-click the action menu for the new user and select Enroll identity.
6. Ensure the Root Certificate Authority is selected and provide the enroll ID and secret that you specified when you
registered the new user.
7. Specify a unique display name for this new identity and export the identity to your wallet.
8. If Node OU support was not enabled when the identity was originally enrolled, then you should use the new exported
certificate and follow the manual update steps 2 - 7 to update the admin certificate in the MSP, peer, orderer, and
channel. Before attempting these steps, review the next section that describes the ordering node override that needs
to be configured if any of the channel member or channel orderer organization admin certs have expired.
Override orderer configuration to allow expired certs for channel updates

After the admin certificate is updated in the MSP, any channels that the MSP belongs to also have to be updated manually. But, if
any of the channel member certificates or channel orderer organization admin certificates have expired, you need to override the
ordering service configuration to temporarily allow expired certificates.
Fabric includes a setting that allows the channel to ignore expiration checks in order for channel updates to be applied to fix
expired certificates. You need to override the NoExpirationChecks setting on each ordering node in the ordering service.
1. Open the ordering service and click the Ordering nodes tab.
2. Open the first ordering node and click the Settings icon.
3. In the side panel, click Edit configuration JSON (Advanced)
4. Under Configuration updates paste in the following snippet:
{
"General": {
"Authentication": {
"NoExpirationChecks": true
}
}
}
5. Click Update ordering node.
6. Repeat these steps for each ordering node in the ordering service.
Now you are able to update the expired certificates in the channel, see steps 4 - 7 for details. When you are finished, you need
to remove the override by using the same process but this time setting the override snippet to:
$ ```json
{
"General": {
"Authentication": {
"NoExpirationChecks": false
}
}
}
```
Using the command line to view certificate expiration

You can also use the command line to check your certificates expiration date. If your certificate was not generated by the
console, for example it was generated by using the Fabric CA client or Fabric SDKs, you need to convert certificates that are in
base64 format into PEM format by running the following command on your local system:
echo <base64_string> | base64 --decode $FLAG > <key>.pem
Run the following command to display the PEM encoded certificate in a human-readable form:
openssl x509 -in <certificate .pem file> -text
The certificate looks similar to the following example:
$ Certificate:
Data:
Version: 3 (0x2)
Serial Number:
20:3d:3e:c5:31:4f:85:7a:30:9f:b5:67:47:3d:b0:10:70:80:f6:18
Issuer: C=US, ST=North Carolina, O=Hyperledger, OU=Fabric, CN=fabric-ca-server-org1CA

Validity
Not Before: Nov 28 19:18:00 2018 GMT
Not After : Nov 28 19:23:00 2019 GMT
Subject: C=US, ST=North Carolina, O=Hyperledger, OU=peer, OU=org1, CN=1peeradmin
...
...
You can find the expiration date in the Validity section and follows Not After: . In this example, the certificate expires on
November 28, 2019.
Export an MSP
MSPs can be exported from the console to your local file system. Navigate to theOrganizations tab and click the MSP that you
want to export. Click the Export icon to download the MSP to a JSON file on your local system.
Figure 13. How to export MSP
Share the JSON file with all of the members of the network who must import it into their console. It is important for them to
import the updated MSP, so that when they create a new channel, they are using the MSP definition with the latest admin
certificate.
Import an MSP
When another organization member shares their MSP with you, importing it into your console is important to ensure you are
using the latest version of their organization MSP.
1. Navigate to the Organizations tab and click Import MSP definition.

2. Browse to the MSP JSON file that was shared with you and clickImport MSP definition.
If you previously imported the MSP into your console, you need to update the definition.
1. On the Organizations tab and click the MSP tile.

2. Click the Settings icon and then Add file to browse to the new JSON file.
3. Click Update MSP. If you created any nodes in your console that use this MSP, they are updated with the new MSP and
restarted.
1. If a certificate expires in more than five years, the expiration date is not visible from the console.↩

Upgrading and deleting deployed nodes

After creating CAs, peers, and ordering nodes, you need to monitor the resources used by the nodes and potentially reallocate
resources.
Target audience: This topic is designed for network operators who are responsible for creating, monitoring, managing, and
upgrading their components in the blockchain network.
After a node has been created, there are three main ways to update it.
1. Update its configuration. Just as it is possible to override configuration parameters when deploying a node, it is possible
to edit many parameters and redeploy the node. For more information, see our topic on Advanced deployment options.
2. Increase the resources allocated to it. If you notice that the performance of a node is beginning to lag or that its storage
is beginning to run out, you can choose whether to deploy a larger node and join it to channels or whether to increase the
resources allocated to your existing node.
3. Upgrade its Fabric version. Every node is deployed using a release version of Hyperledger Fabric. When new versions of
Fabric become available on IBM Blockchain Platform, Upgrade available is visible on the tile representing the node. While
upgrading to a new version of Fabric is always recommended, unless is rendered necessary by the capabilities of channels
you want to join, it is typically optional. For more information, check out Upgrading to a new version of Fabric.
In this topic, we'll cover the process for reallocating resources, upgrading to a new version of Fabric, and deleting nodes.
Considerations when reallocating resources
Important: Resizing a node requires the containers to be rebuilt, which can cause a delay in the functioning of the node.
Note: We recommend using the IBM Cloud Monitoring tool in combination with your IBM Cloud Kubernetes dashboard to
monitor your Kubernetes resource usage. When you determine that a worker node is running out of resources, you can
add a new larger worker node to your cluster and then delete the existing working node.
While it takes less effort to deploy enough resources to your Kubernetes cluster from the start and therefore be able deploy and
expand resources without having to increase the resources in your cluster, the bigger the deployment, the more it will cost.
Users need to consider their options carefully and recognize the tradeoffs that they are making regardless of the option that they
choose.
You can scale your cluster manually by monitoring your nodes and either adding more nodes or larger nodes. While this process
can be labor intensive, it has the advantage of allowing the user to always be certain what is being charged to their cloud
account.
A Kubernetes cluster on IBM Cloud includes the ability to use anautoscaler that can scale your worker nodes up or down in
response to your pod spec settings and resource requests. For more information about the autoscaler and how to set it up, see
Scaling Kubernetes clusters or Scaling OpenShift clusters in the IBM Cloud documentation. Note that allowing the autoscaler to
adjust your resources will result in charges to your IBM Cloud account that will vary automatically with your usage.
To scale manually in the console, click the node that you want to adjust on theNodes page and then click the Usage tab. You
can see a button called Reallocate, which will launch a Resource allocation tab that is very similar to the one that you saw when
you created the node. If you want to lower the amount of available resources, simply provide lower values and click Reallocate
resources on that tab and the resulting Summary page.
If you want to increase the CPU and memory for a node, use theResource allocation panel in the console to increase the
values. The white box at the end of the page adds up the new values. After clicking Reallocate resources, the Summary page

will translate this value into a VPC amount, which is used to calculate your bill. You'll then need to navigate to your Kubernetes
cluster to make sure your cluster has sufficient resources for this reallocation. If it does, you can click Reallocate resources. If
sufficient resources are not available, you must increase the size of your cluster.
The method you will use to increase storage will depend on the storage class you chose for your cluster. Refer to theKubernetes
or OpenShift storage options in the IBM Cloud documentation. If you are about to exhaust the storage on your peer or ordering
node, you might need to deploy a new peer or ordering node with a larger file system and let it sync via your other components
on the same channels.
In IBM Cloud, CPU and memory can be increased using the console if you have resources available in your Kubernetes cluster on
IBM Cloud. However, storage must be increased using the IBM Cloud CLI. For a tutorial on how to do this, see Changing the size
and IOPS of your existing storage device on your Kubernetes or OpenShift cluster.
Tip: Note that you do not need to adjust the CPU, memory, or storage for your smart contract pods. These pods will
automatically use as many resources as they need to function efficiently. In cases where your smart contracts are
struggling because of insufficient resources, you will have to address this at the cluster level.
Monitoring file storage

If you are using Classic infrastructure, to view your consumption of file storage, navigate to your Kubernetes cluster on IBM
Cloud. Click on the menu icon . Then click Classic infrastructure > Storage > File Storage. This will display the
capacity and usage for each persistent volume claim (PVC). This usage can be mapped to your IBM Blockchain Platform nodes
by clicking on the cell in the Notes column.
You will see something that looks like this:
$ PVC {"plugin":"ibm-file-plugin-77497497cc-5qm58","region":"us-
south","cluster":"05ccfca248dc4c389978d074524e0a8e","type":"Endurance","ns":"n4c817f","pvc":"n4c817forg1ca
-fabric-ca-pvc","pv":"pvc-63074ac8-8b9b-11e9-88db-
222bd59fb4bc","storageclass":"default","reclaim":"Delete"}
To see the same information from the command line, log in to your cluster and enter this command:
$ ibmcloud sl file volume-list --column id --column notes
This will allow you to map the output from the pods to the nodes you have deployed.
If you are using VPC infrastructure, see About block storage for VPC for more details.
Adding storage
As you monitor your pods and notice that more storage is needed, you can increase storage when additional storage is available.
The following links provide more information about how to increase storage after your network is deployed.
IBM file storage

Portworx
Block storage
Users can allocate more storage to their running network by resizing the existing storage PVCs or by deploying nodes with new
PVCs.
Upgrading to a new version of Fabric

Important: Support for Hyperledger Fabric v1.4 is now deprecated, and support for Fabric v1.4 will be removed from
IBM Blockchain Platform on March 31, 2023. Users should therefore upgrade to Fabric v2.2 as soon as possible. Your
applications may require changes as a result of upgrading to v2.2, so please plan for appropriate testing. Note that Fabric
v1.4 has not been supported by the Hyperledger community since April of 2021. In addition, Fabric v1.4 uses Golang
v1.14, which is no longer receiving security updates from the Golang community.
While some new versions of Fabric only require updating the Fabric version on nodes, some include new channel capabilities
that must also be updated.
In these cases, the process of "updating to the latest" release is, at a high level, a two step process:
1. Upgrade the Fabric version on all nodes.

2. Update the channels to the new capability levels. For information about how to update channels, see Capabilities.
Important: You must upgrade nodes before you update the channels. If a node attempts to read a configuration block
containing a capability level it does not understand (which is true in cases where the capability is a higher level than the
node version), the node will crash on all channels. The node must then be upgraded to the appropriate Fabric version
before it can be used again.
The process of upgrading a node involves two main steps:
1. Backing up the persistent volumes associated with the node. These backups ensure that in the case of an upgrade failure
in which the peer pod is corrupted that the node can be re-deployed using the ledger. For more information, see Backup
considerations for each node type.
2. Upgrading the Fabric versions of the nodes one at a time (also known as a "rolling upgrade").
Tip: It may also be necessary to update SDKs and smart contracts before you can take advantage of the latest Fabric
features. For more information, check out Step three: Update SDKs and smart contracts.
Upgrading nodes from Fabric v1.4 to v2.2

Use the following recommended procedure to upgrade your Fabric v1.4 peer and orderer nodes to v2.2, regardless of whether
you are also migrating your v1.4 chaincode to run on Fabric v2.2. Once on v2.2, you can migrate your nodes to v2.4.
Attention: To update to Fabric v2.2, the recommended process (below) adds a new peer, rather than updating an existing peer
in place. Adding a new peer avoids the extended time to rebuild CouchDB (if applicable) and downtime when an existing peer is
updating. The final step then deletes the replaced peer.
Update your CAs

Update your Certificate Authority (CA) nodes before you upgrade your peer and orderer nodes, as follows:
Attention: Most application solutions do not interact with CAs continually, in which case CAs can be upgraded with no impact to
application usage. However, any application flows that use fabric-ca functionality may be unavailable for 1-2 minutes during the
update.
1. Using your console, navigate to your Certificate Authority and select the first CA node. Click onupgrade available and
select 1.5.5-2 or later.
2. The CA node will restart with the upgrade installed.
3. Repeat the steps for each CA node.
Update your orderers

After updating your Certificate Authority (CA) nodes, update your orderer nodes, as follows:
1. Using your console, navigate to the ordering service and select the first ordering node. Click onupgrade available and
select 2.2.10-1 or later. Click through the confirmations dialogs.
2. The node will restart using the 2.2.10-1 (or selected) image. Transaction processing will continue during the node restart,
because the remaining four orderer nodes make a quorum. The selected orderer node will be unavailable for 1-2 minutes
during the update. ATTENTION!!: If the updating orderer node does not restart and come back online successfully, please
contact IBM Support. DO NOT attempt to update any remaining orderer nodes before contacting IBM Support.
3. Repeat the procedure for each remaining orderer node.
Update your peers

After updating both your Certificate Authority (CA) and orderer nodes, update your peer nodes, as follows:
ATTENTION!!: When creating new v2.2 peers using the steps below, selecting 2.2.10-1 is highly recommended - other
selectable versions may have chaincode implications.
1. Before upgrading any peer with CouchDB installed, you must rebuild the CouchDB state database from CouchDB v2.x to
v3.x. The recommended process is to add a new peer, and then let the database synchronize. This removes the downtime
that would occur when upgrading in place. Then continue as follows, for peers both with and without CouchDB:
2. Add a new peer using your console. Do NOT install chaincode on the new peer.
3. Remove the new peer from both peer gossip and service discovery, as follows:
a) Get the Custom Resource Definition (CRD) of the new peer, by running:
kubectl get ibppeer -n [NAMESPACE]
b) Back up the CRD: kubectl get ibppeer [IBPPEER_NAME] -n [NAMESPACE] -o yaml > ibppeer_crd_backup.yaml
c) Edit the CRD: kubectl edit ibppeer [IBPPEER_NAME] -n [NAMESPACE]
d) Change spec.peerExternalEndpoint: to do-not-set as follows: spec.peerExternalEndpoint: do-not-set
e) Delete the peer deployment: kubectl get deployment -n [NAMESPACE] and then: kubectl delete deployment
[PEER DEPLOYMENT NAME] -n [NAMESPACE]
f) The peer will restart - then it should not be discoverable by application service discovery. DoNOT update the client
connection profiles at this time.
4. Add the new peer to the channel(s) that existing peers are participating in. DoNOT install channel chaincode on the new
peer.
5. Let the new peer synchronize its blocks, to the block height of the existing peers.
6. Reenable PEER_GOSSIP on the new peer, as follows:
a) Get the Custom Resource Definition (CRD) of the new peer, by running: kubectl get ibppeer -n [NAMESPACE]
b) Back up the CRD: kubectl get ibppeer [IBPPEER_NAME] -n [NAMESPACE] -o yaml > ibppeer_crd_backup.yaml
c) Edit the CRD: kubectl edit ibppeer [IBPPEER_NAME] -n [NAMESPACE]
d) Change spec.peerExternalEndpoint to a blank string, using empty quotation marks, as follows:

spec.peerExternalEndpoint: ""
e) Delete the peer deployment: kubectl get deployment -n [NAMESPACE] and then: kubectl delete deployment
[PEER DEPLOYMENT NAME] -n [NAMESPACE]
f) The new peer will restart - then it should begin participating in service discovery and getting new blocks. Application

targeting will depend on the connection profile and application logic.
7. Install chaincode on the new peer.
8. Test the new environment by running applications with all peers (original and new) enabled.
9. (Recommended) Test applications by turning off the peer that is being replaced, as follows:
a) Run: kubectl patch [ibppeer-name] -n [namespace] -p= [{"op": "replace", "path":"/spec/replicas", "value":0}] -
type=json
b) Ensure application continuity with the original peer is NOT running.
10. Delete the original peer.
11. Repeat the prior steps for each peer you are updating.
Important: Upgrading IBM Blockchain Platform nodes directly from Hyperledger Fabric 1.4.x to the latest Fabric version
is possible, but deploying a new Fabric 2.2.x peer instead of upgrading is recommended. Fabric installation is done by
IBM Blockchain Platform, but can take hours or days depending on the size of the database to be built. See the Fabric
documentation on upgrading for more information.
If your Fabric v1.4 nodes use Node.js chaincode, use the following sequence to upgrade these nodes from Fabric v1.4 to v2.4:
1. Deploy new peers with Fabric v2.2

2. Update the Node.js chaincode on these peers to 2.4 shim
3. Install and instantiate the new chaincode
4. Upgrade the peers from Fabric v2.2 to v2.4.
Step one: Back up your ledger (optional)

It is recommended to take regular backups of the persistent volumes of your nodes as part of the normal process of network
administration. For example, in our topic on backing up and restoring components and networks, an example schedule is
provided which recommends that backups be taken of the ordering nodes and the peers (including the state database of the
peer, if using CouchDB) each night.
However, if you are not taking regular backups, it is recommended that you minimally take a backup before attempting to
upgrade a node, as it allows for a node to be restored to an earlier running state in cases where the upgrade fails. For
information about how to backup your nodes by taking a snapshot of the relevant persistent volumes, check out Taking
snapshots.
Step two: Upgrade your nodes one at a time
Tip: If you are upgrading both peer and ordering node binaries, it is a best practice to upgrade the ordering nodes first, as
ensuring that the ordering nodes (and by extension, the ordering service) is functioning correctly is more important to the
health of your network as a whole than the functioning of any particular peer.
The process for upgrading a node is relatively straightforward. First, make sure you are using the console where the node was
created. You cannot use the console to update imported nodes. When a node upgrade is available, Upgrade available is visible
on the node tile. If Upgrade available does not appear on the tile when it should be there, make sure your console is using the
latest version using the Refresh cluster feature.

You can then update the node:
1. Click on the tile representing the node.

2. The upgrade panel can be accessed either by clicking theInfo and usage tab, next to the Upgrade available notice, or the
Fabric version box. Clicking either one opens the Upgrade Fabric version side panel.
3. On the Upgrade Fabric version side panel, review the version of your node and the version you are upgrading to. If this is
right, click Next.
4. On the next panel, confirm the information and enter the name of the node being upgraded.
The node will be unavailable during the upgrade. The status was turn grey and will readStatus unknown or Unavailable. When
the upgrade has completed, the status will turn green and be Ready. If the upgrade fails and the node lapses into an
unrecoverable state, follow the instructions for Restoring nodes from a snapshot.
It is a best practice to only upgrade one node of each type at a time. In other words, if you need to upgrade both peers and
ordering nodes, you can start a single peer upgrade and a single ordering node upgrade at the same time. However, do not
attempt to upgrade multiple peers or multiple ordering nodes at the same time, as this threatens the availability of your
components.
It is not possible to upgrade an ordering node if any node in your ordering service is down for any reason. Coordinate with all of
the administrators of your ordering service before attempting to upgrade.
Step three: Update SDKs and smart contracts
Tip: It is a best practice to upgrade your SDK to the latest version as part of a general upgrade of your network. While the
SDK will always be compatible with equivalent releases of Fabric and lower, it might be necessary to upgrade to the latest
SDK to leverage the latest Fabric features. Also, after upgrading, it's possible your client application may experience
errors. Consult the your Fabric SDK documentation for information about how to upgrade.
Node
Go

Java
plugins {
id 'java'
}
repositories {
...
maven {
}
}
Init functions
For a look at how the new lifecycle is administered in the console, check out Deploy a smart contract using Fabric v2.x. For a
look at the possibilities the new lifecycle opens up, check out Writing powerful smart contracts.
Step four: Update capabilities

Once your nodes, SDKs, and smart contracts have been upgraded to use the latest Fabric version, you can update your channel
configuration to use the latest capabilities. Note that the Fabric version of your nodes must be at least at the corresponding
capability level of the channel the node is joined to.
For more information about capabilities and how to update a channel configuration to enable them, check out Capabilities.
Deleting components

The best practice for deleting components is to delete them using the console. This will also delete all of the artifacts associated
with a node including your ledger data in persistent storage and the keys that are stored as secrets. Deleting a peer will not,
however, delete any smart contract pods associated with it. These must be deleted separately. Deleting a component is usually
achieved by logging onto the console where a component was created or installed, clicking on the component and finding the
related trash can icon. You will typically be prompted to type the name of the component and to confirm your decision. You can
also delete nodes by using the IBM Blockchain Platform APIs.
However, there are cases in which this type of deletion will not be successful. For example, occasionally when a node fails to
deploy it will not be possible to delete it using the console. The same can be true if the console loses connection with the cluster
for some reason.
In these cases, it will be necessary to use the Kubernetes dashboard or delete the node or relevant pods manually. If you
attempt to delete pods that contain deployments such as peers, CAs, or ordering nodes, the pod will automatically restart and
not be permanently deleted.
Important: Because smart contracts installed on a 2.x peer are deployed into their own pods and not directly into the
peer container, they will not be deleted when a peer is deleted. They will have to be deleted either using the UI of your
cluster or by issuing kubectl commands. Smart contracts installed on a v1.4.x peer will be deleted when the peer is
deleted.
Because deployments are organized in Kubernetes by their "namespace", you need to know your Kubernetes cluster namespace
before you can delete components using the kubectl CLI. From the console, open any CA node and click the Info and Usage
icon. View the value of the API URL. For example: https://nf85a2a-soorg10524.ibpv2-cluster.us-
followed by a random string of six alphanumeric characters. So in the example above the value of the namespace is nf85a2a .
If you want to delete all of your smart contract pods, you can issue this command:
kubectl get po -n <NAMESPACE> | grep chaincode-execution | cut -d" " -f1 | xargs -I {} kubectl delete
po {} -n <NAMESPACE>
If you want to delete a single smart contract pod, you will first have to figure out the name of your smart contract pod.
First, get a list of all of the smart contract pods running in your cluster:
$ NAME READY STATUS RESTARTS AGE

LABELS
chaincode-id=javacc-1.1,peer-id=org1peer1
chaincode-id=nodecc-1.1,peer-id=org1peer1
Your smart contract name and version is visible next to the chaincode-id.
To delete a single pod, issue this command, substituting the <POD_NAME> for the name of your pod, for example the smart
contract pod chaincode-execution-0a8fb504-78e2-4d50-a614-e95fb7e7c8f4 , as well as your <NAMESPACE> :

kubectl delete pod <POD_NAME> -n <NAMESPACE>
You can also use kubectl commands to delete all of the nodes in your cluster by issuing commands to delete each type of node.
First, set the namespace where the nodes you want to delete are located:
kubectl config set-context --current --namespace=<NAMESPACE>
Then run the following commands to delete all of your blockchain nodes:
kubectl delete ibpca --all

kubectl delete ibppeer --all
kubectl delete ibporderer --all
You may also choose to only delete all of a single type of node within a namespace, for example, by only issuingkubectl
delete ibppeer --all .
Tip: Note that if you delete your entire namespace, your smart contract pods will also be deleted. Your smart contract
pods will also be deleted, along with your nodes, if you delete your service instance using the Kubernetes dashboard in
IBM Cloud.
Operating nodes with operations service

The IBM® Blockchain Platform includes an Operations Service feature that was introduced in Hyperledger Fabric v1.4.0. The
feature provides a RESTful “operations” API for operators to perform node health checks, pull operational metrics from the peer
and orderer nodes, and manage logging levels. The peer and the orderer nodes host an HTTP server that offers the RESTful
“operations” API. For more information about the Operations Service provided by Hyperledger Fabric, see The Operations
Service.
Considerations and limitations

All peer and orderer nodes are configured with clientAuthRequired: false so that the health checker can be
accessed. Because clientAuthRequired is set to false and also mutual TLS is enabled, when you access the REST
server, you need to pass the TLS identities to be able to authenticate. This setting ensures that only users with the
appropriate keys can see the corresponding logs.
Only the metrics pulling model that is based on Prometheus is supported for now.
Before you begin

You need to gather the following information from your peer and orderer.
peer-endpoint or orderer-endpoint
You can find the operations endpoint URL of the peer or orderer in the peer or orderer JSON file that you export from the
console.
1. Click the peer or orderer in the Node tab.

2. On the peer or orderer page, click the Settings icon besides the peer or orderer name.
3. In the side panel, click Export to save the peer or orderer JSON file.
4. Find the operations endpoint URL that is the value of the operations_url parameter in the JSON file. This value is
referred to as the peer-endpoint or orderer-endpoint in the commands later in this topic. For example:
{
"short_name": "Peer1Org1_0",
"name": "Peer1 Org1",

"url": "https://169.46.208.93:32739",
"type": "fabric-peer",
"operations_url": "https://169.46.208.93:32101"
}
{
"short_name": "Orderer_0",
"name": "Orderer",
"url": "https://169.46.208.93:31612",
"type": "fabric-orderer",
"msp_id": "orderermsp",
"operations_url": "https://169.46.208.93:30115"
}
client-tls-cert and client-tls-key
You can find the certificate and private key of the TLS CA in the console.
1. Click the peer or orderer's CA node in the Node tab.

2. On the CA tab, click the actions menu next to theadmin user and click Enroll identity.
3. On the side panel that opens, select TLS Certificate Authority from the Certificate Authority drop-down list.
4. Enter the Enroll secret for the admin user and click Next.
5. Enter an Identity display name and click Add identity to Wallet.
6. Open the Wallet tab and click the identity you just created.
7. Click Export identity to download the Certificate and Private key to a JSON file.
8. Open the exported JSON file.
9. Find the private key that is the value of the private_key parameter in the JSON file. This is your client-tls-key
for use in the commands below.
10. Find the TLS CA certificate that is the value of the cert parameter in the JSON file. This is your client-tls-cert
for use in the commands below.
peer tls-ca cert or orderer tls-ca cert
You can find the TLS CA certificate of the peer or orderer in the console.
1. Click the peer or orderer's node in the Node tab.

2. Click the Settings icon beside the node name.
3. Copy the node's TLS CA certificate string. This is your peer tls-ca cert or orderer tls-ca cert that can be
used in the commands below.
Note: For all the certificates and keys, you must convert the certificate strings, which are in base64 format, to individual .pem
files by using the following commands:
$ ```
echo <base64_string> | base64 --decode $FLAG > <key_name>.pem
```
Checking node health

Run the curl -k <peer-endpoint>/healthz or curl -k <orderer-endpoint>/healthz command to check the health of
the peer or orderer node. For example:
curl -k https://169.46.208.93:3210/healthz
For more information about health checks, see Health checks.

Viewing the metrics
Run the following command to view the peer metrics. To view the orderer metrics you would run the same command but
replace the <peer-endpoint> with the <orderer-endpoint> .
curl -k <peer-endpoint>/metrics --cert <client-tls-cert> --key <client-tls-key> --cacert <peer tls ca-
cert>
For example:
curl -k https://169.55.231.152:30766/metrics --cert msp/org1/ca/tls/msp/signcerts/cert.pem --key

msp/org1/ca/tls/msp/key.pem --cacert msp/org1/ca/tls/msp/cacerts/tlsca.pem
For more information about metrics, see Metrics.
Viewing logging levels

Run the following command to view the logging level. You will see the log level on your terminal after the command completes.
curl -k <peer-endpoint>/logspec --cert <client-tls-cert> --key <client-tls-key> --cacert <peer tls ca-
cert>
For example:
$ curl -k https://169.46.208.93:3210/logspec --cert msp/org1/ca/tls/msp/signcerts/cert.pem --key

msp/org1/ca/tls/msp/keystore/key.pem --cacert msp/org1/ca/tls/msp/cacerts/tlsca.pem
You can see the result that is similar to the following example:
$ {"spec":"info"}
Setting logging levels

To change the existing logging level setting, run the following command, which uses the PUT method with JSON body that
consists of a single attribute named spec . Replace <log-level> with your expected logging levels. For more information
about the logging levels that you can set, see Logging specification in Hyperledger Fabric documentation.
curl -X PUT <peer-endpoint>/logspec -d '{"spec":"<log-level>"}' --cert <client-tls-cert> --key

<client-tls-key> --cacert <peer tls ca-cert>
For example:
$ curl -X PUT https://169.46.208.93:3210/logspec -d '{"spec":"chaincode=debug:info"}' --cert

msp/org1/ca/tls/msp/signcerts/cert.pem --key msp/org1/ca/tls/msp/keystore/key.pem --cacert
msp/org1/ca/tls/msp/cacerts/tlsca.pem
After you set a new logging level, you can use the view logging level command to check your settings.
For more information about log level configuration, see Log level management in Hyperledger Fabric documentation.
osnadmin service endpoints

The Hyperledger Fabric osnadmin service allows administrators to perform channel-related operations for ordering service
nodes.
To list channels that are using an osnadmin service endpoint, run:

$ curl https://osntest-ordereranode1-admin.openshift4x-ibpv2-test-68e10f583f026529fe7a89da40169ef4-
0000.us-south.containers.appdomain.cloud:443/participation/v1/channels --cert
/tmp/msp/orderera/ca/tls/msp/signcerts/cert.pem --key
/tmp/msp/orderera/ca/tls/msp/keystore/06fa54a3978e9df58778bce22b9140f043df920eb03150d1284d3579f70d57b5_s
k --cacert /tmp/msp/orderera/ca/tls/msp/cacerts/tlsca.pem
The response should be similar to:
$ {
"systemChannel": {
"name": "testchainid",
"url": "/participation/v1/channels/testchainid"
},
"channels": [
{
"name": "mychannel",
"url": "/participation/v1/channels/mychannel"
}
]
}
To list details for an application channel that is using an osnadmin service endpoint, run:
$ curl https://osntest-ordereranode1-admin.openshift4x-ibpv2-test-68e10f583f026529fe7a89da40169ef4-
0000.us-south.containers.appdomain.cloud:443/participation/v1/channels/mychannel --cert
/tmp/msp/orderera/ca/tls/msp/signcerts/cert.pem --key
/tmp/msp/orderera/ca/tls/msp/keystore/06fa54a3978e9df58778bce22b9140f043df920eb03150d1284d3579f70d57b5_s
k --cacert /tmp/msp/orderera/ca/tls/msp/cacerts/tlsca.pem
The response should be similar to:
$ {
"name": "mychannel",
"url": "/participation/v1/channels/mychannel",
"consensusRelation": "consenter",
"status": "active",
"height": 13
}
For additional osnadmin information, see osnadmin channel in the Hyperledger Fabric documentation.
Removing a system channel

Hyperledger Fabric v2.2 introduced the capability to create application channels, using Channel Participation APIs. Prior to
v2.2, all application channels were created with transactions on the system channel. Legacy system channels are therefore now
obsolete, and can (and should) be removed for improved security and performance. The Fabric Operations Console has added
support for system channel removal, as of version v1.0.3-25.
With the latest Fabric Operations Console you can:
Manage ordering nodes (aka orderers) that are not on a system channel
Manage application channels that were created with Channel Participation APIs
Remove the system channel (and application channels) from ordering nodes (aka unjoin a channel)
System channel support remains, however removing the system channel is recommended.
Attention If you remove the system channel from an existing network, and you use Node.js chaincode, you should upgrade in
stages - see Upgrading Node.js chaincode below for details.
Target audience: This topic is designed for architects and system administrators who are responsible for planning, configuring,

and installing IBM Blockchain 2.5.3. Application channels are identical regardless of the creation method used.
Benefits
Operating without a system channel has the following benefits:
Increased privacy - A system channel is a shared entity for all organizations on the network. It is therefore impossible to hide
the existence of application channels, and their member organizations, from other members. By contrast, operating without a
system channel obscures all channel names and their members from other member organizations.
Increased performance - A system channel consumes a small amount of CPU, networking and storage resources that can be
instead utilized for application transactions. The capability to unjoin channels also enables optimizing ordering nodes, by
recovering CPU, storage and networking resources from application channels that are no longer needed.
Enhanced channel maintenance - The channel participation APIs are lighter weight, easier to use, and deliver additional
features, resulting in reduced code requirements for managing channel policies.
Systemless orderers details

This section, for network administrators, describes the details of an ordering servicewithout a system channel. When a system
channel is used for creating an ordering service, each ordering node receives a configuration block that is generated prior to
creating the orderer container. Each ordering node gets this configuration block to bootstrap it and bring it online. By contrast,
when using systemless ordering nodes this process has changed.
With no system channel, an orderer is simply created and started. It does not wait for a genesis block before becoming online.
The node will be online immediately and the channel participation APIs are available to use. Once an orderer has joined a
channel via a channel participation API request it will be considered either a consenter or follower of the application
channel. A consenter has its TLS certificate listed in the consenters field in the channel's configuration block, which
authorizes the node to participate in the ordering of transactions. A follower ordering node has joined an application channel,
but is not listed in the consenters field and cannot order transactions. Follower nodes can download the ledger to enable data
redundancy without additional consenter networking and communication overhead. Note that a follower orderer can always be
upgraded to a consenter orderer, and vice versa, by editing the application channel's config block.
Removal of the system channel means that the legacy concept of orderering nodes belonging to a centralized group (the
consortium of network organizations) is obsolete. Orderering nodes without a system channel are a much more loosely grouped
entity. They may or may not be members of the same channels, and each orderer can choose to join or unjoin any application
channel. This also means that appending orderers to an existing ordering cluster, and creating the ordering cluster from scratch,
now both follow the same path. Which is to create and start the orderers and then join them to an application channel.
Removing an existing system channel

The process of removing an existing system channel is to remove the system channel configuration from each ordering node.
You should first place the system channel into maintenance mode (step 2 below) to prevent any application channels from being
created while the system channel is being removed. You will then unjoin the system channel from each orderer node (step 3
below) using the Fabric Operations console, as follows:
1. Ensure that each ordering node in the Ordering Service is running Fabric v2.4.x or higher
2. Place the system channel into maintenance mode, using the Fabric Operations console UI, as follows:
From the Nodes tab, click the Ordering cluster tile
Click the Ordering nodes tab
Click the settings (gear) icon
Click the Maintenance button
Follow the prompts to turn maintenance mode on

3. Remove the system channel from all ordering nodes, using the Fabric Operations console UI, as follows:
From the Nodes tab, click the Ordering cluster tile
Remain on the Details tab
Click the unjoin (trash can) icon on the system channel tile
Follow the prompts to unjoin each ordering Node.js from the system channel
4. Complete the process by upgrading the Node.js chaincode from Peer v1.4.x to v2.4.x

After you click the ordering cluster tile you may see a warning about missing a TLS identity. This identity is a different type than
we've used in the past and is only need for orderers that do not have a system channel. This identity is actually the same identity
the orderer is using when it enrolls on startup against the TLS CA. To get this identity:
1. From the Nodes tab, select the CA tile that this orderer cluster used (during create)
2. Find the row for the identity this orderer used and click the dot dot dot
3. On the enroll wizard select the TLS CA in the CA drop down (its important to select the TLS CA)
4. Type the enroll secret that was used earlier when creating the orderer
5. Follow any other directions in the enroll wizard and click submit
6. If you browse back to the nodes page and select the Orderer Cluster tile the TLS identity error should be gone
Upgrading Node.js chaincode

You may need to be cautions about upgrading peers and orderers to use the system channel removal features. Hyperledger
Fabric v2.4 updated its chaincode version of Node.js to v16 and removed support for the earlier Node.js v12. If you are
upgrading your peers and orderers to use the channel participation APIs, and are using Node.js v12 based chaincode, you must
also incrementally upgrade the Node.js chaincode, as follows:
1. Upgrade any v1.4.x peers to v2.2.x (note that earlier Node.js v12 chaincode will continue to work, because Fabric v2.2.x
provides both Node.js environments (v12 and v16)
2. Update your chaincode locally to use a Node.js v16.14.2 (or later v16.x.x) environment
3. Perform a Fabric chaincode upgrade on each channel where this chaincode is used
4. Upgrade your v2.2.x peers to Fabric v2.4.x

Developing smart contracts and applications
Developing smart contracts with IBM Blockchain Platform Developer Tools
The IBM® Blockchain Platform Developer Tools provide an environment within Visual Studio Code for developing, packaging, and
testing smart contracts. You can use the tools to create your smart contract project and get started developing your business
logic. You can then use the tools to test your smart contract either on your local machine by using a preconfigured instance of
Hyperledger Fabric, or by connecting to an IBM Blockchain Platform network, before you deploy the smart contract to the IBM
Blockchain Platform. This tutorial describes how to install and use the Developer Tools.
Note: The IBM Blockchain Platform extension works seamlessly with any instance of the IBM Blockchain Platform that
uses Hyperledger Fabric versions 1.4 and later. This tutorial is oriented toward users of the high-level Fabric smart
contract programming model. If you are using low-level smart contract APIs, you can find additional instructions in the
IBM Blockchain Platform extension documentation. For more information, see the Writing Your First Chaincode tutorial in
the Fabric documentation.
Before you begin

Prerequisites
Windows 10, Linux, or Mac OS are currently the supported operating systems.
VS Code version 1.40 or greater.
Docker version v17.06.2-ce or greater.
If you are developing Go smart contracts, you need to install Go version v1.12 or greater. Note that if you are using Fabric
v2.x, you will need Go version v1.13 or higher instead.
If you are developing Node smart contracts, you need to install Node ^10.15.3 or ^12.15.0 and npm v6.x or greater.
Considerations if you are developing Java smart contracts:
Java 11 is required to execute Java smart contracts.

Gradle v4.x is used to build Java smart contracts.
Custom Gradle versions can be used by using a Gradle wrapper.
Java smart contracts must use fabric-chaincode-shim at v1.4.6 or later (if deploying on a peer that uses a Fabric 1.4.x
image; peers that use a Fabric 2.x image do not require a shim), as this version is the first version that includes support for
Java 11.
For an example of a Java smart contract, see the Basic asset transfer smart contract.
If you are using Windows, you also must ensure the following:
Docker for Windows is configured to use Linux containers (by default).

You installed the C++ Build Tools for Windows from windows-build-tools.
You installed OpenSSL v1.0.2 if you are working with smart contracts that use Fabric v1.4 dependencies and want to run
the generated functional tests.
Install the normal version, not the version marked as "light".
Install the Win64 version into C:\OpenSSL-Win64 on 64-bit systems.

If you installed Node and npm by using a manager such as 'nvm' or 'nodenv', you need to set the default or global version.
You can then restart VS Code for the version to be detected by the Prerequisites page.
Step one: Guided tutorials in VS Code

The IBM Blockchain Platform Developer Tooling includes guided tutorials to help you get started. The tutorials provide step-by-
step instructions on how to develop and test your smart contract project, as well has how to deploy the smart contract to a
network on IBM Cloud. You also can find sample smart contracts that are available for you to download.
To navigate to the tutorials from within VS Code, click the blockchain icon in the left navigation and then click the IBM
Blockchain Platform icon at the upper right corner to view the extension homepage. On the homepage, you can find a link to the
tutorials gallery and the sample smart contracts.
Figure 4. Click on the IBM Blockchain icon in the upper right corner to navigate to the tutorials and sample code
Step two: Create a smart contract project

You can use the extension to create a new smart contract project in Visual Studio Code. The extension creates a basic smart
contract that manages an example asset in the language of your choice. You can use the structure of the example as a starting
point for developing your own business logic. The extension provides all the dependencies that are required to deploy your smart
contract to an instance of Hyperledger Fabric.
1. Click the IBM Blockchain icon to open the IBM Blockchain tab. Click the overflow menu in the smart contracts pane and
click Create New Project.
2. Select the smart contract type to generate. The Default Contract example is recommended for first-time users and
demonstrates how to perform create, read, update, and delete operations to the public ledger that's shared by all network
members. The Private Data Contract example demonstrates how to perform create, read, update, delete, and verify

operations to a collection, that is private to a single network member.
3. Select the language that you want to create a smart contract in. The current options are JavaScript, TypeScript, Go, and
Java. Note: If you are deploying the smart contracts to a production network, JavaScript and TypeScript smart contracts
require more resources than contracts written in Go.
4. Select an asset to be managed by the example contract. For example,bond.
5. Create a folder with the name of your project and open it.
6. Select how to open your new project. The project folder should now open.
When the project opens, you can find the new smart contract in the explorer window in the left pane. The structure of the project
depends on the language that you selected. However, each smart contract contains the same elements:
The source code of the smart contract. If you selected to create a JavaScript or TypeScript contract, the extension builds a
basic smart contract by using the fabric-contract-api with a series of functions that manage your example asset. For
example, if you selected bond, you can find the functions of createBond, updateBond, readBond, bondExists, and
deleteBond.
A test file.
The accompanying smart contract dependencies.
Do I need to update my smart contract for Fabric v2.x?

Node
Go
Java
plugins {

id 'java'
}
repositories {
...
maven {
}
}
Init functions
Step three: Package a smart contract

You need to package a smart contract before you can install it on your IBM Blockchain Platform network or the preconfigured
Hyperledger Fabric network. Fabric V1 channels require smart contract packages to be in the.cds format, and V2 require the
.tar.gz format. Complete the following steps to package your smart contract:
1. Open your smart contract project in VS Code by clicking File and then click Open .... You can also click Open Workspace if
you saved your project as a workspace. Ensure that you have the smart contract project open in the file viewer.
2. Click the IBM Blockchain icon to open the IBM Blockchain tab.
3. In the Smart Contracts pane, click the overflow menu and select Package Open Project. You are asked for the name of
the package and the version. You will also need to select whether you want to package it as a .tar.gz (for deploying to a
channel with V2 application capability) or .cds (for deploying to a channel with V1 application capability). To find out the
channel capabibilities/version, hover your mouse over the channel in the Fabric Environments panel that you wish to
deploy to. This will display a tooltip containing the channel capabilities.
If you have one smart contract project, it is packaged automatically and be displayed in theSmart Contracts pane.
If you have multiple smart contract folders open, you are asked which one to package.
If you have no smart contract folders open, you get an error message.
If you want to control which files in the project are packaged, you can create a .fabricignore file in the top-level directory of
your smart contract project. The file and pattern format for a .fabricignore file is the same as a .gitignore file, for
example:
$ /.classpath

/.git/
/.gradle/
/.project
/.settings/
/bin/
/build/
Exporting, importing, and deleting a smart contract package

After you package a smart contract project, you can export it from VS Code:
1. In the IBM Blockchain Platform extension panel, right-click the smart contract package and selectExport Package.
2. Choose the directory to save your smart contract package file and clickExport.
You can also import an existing smart contract package into the IBM Blockchain Platform pane:
1. In the Smart Contracts pane, click the overflow menu and select Import a Package.
2. Browse to the smart contract package that you want to import, and clickImport.
You can also click Delete Package to remove the smart contract package from the list of packages.
Step four: Deploy a smart contract to a preconfigured Hyperledger Fabric network

You can use the VS Code extension to deploy your smart contract to a preconfigured Hyperledger Fabric network that the
extension creates on your local machine. If you are deploying to a V1 capability enabled channel, you need to install and
instantiate your smart contract. If you are deploying to a V2 capability enabled channel that uses the new Fabric 2.x lifecycle
process, you need to install then "approve" and "commit" a smart contract, as opposed to instantiating it.
To deploy a smart contract to a preconfigured network, you can use an existing IBM Blockchain Platform network. See the
instructions in Step six to connect to that network.
Deploying a preconfigured Hyperledger Fabric network

Before you can deploy a smart contract, use the following steps to deploy the preconfigured network:
1. Ensure that Docker is running on your machine.

2. Open the IBM Blockchain Platform tab in VS Code.
3. In the Fabric Environments pane, click 1 Org Local Fabric. If Docker is running, the local instance should be started once
the Hyperledger Fabric images are downloaded.
4. Click 1 Org Local Fabric - Org1 Gateway in the Fabric Gateways pane to connect to the local network.
The VS Code extension creates a basic Fabric network that includes one orderer, one peer, and one certificate authority. The
peer is joined to a channel named mychannel . You can find the list of nodes, organizations, and channels that belong to the
network in the Fabric Environments pane. Above these nodes, you can find the list of smart contracts that are deployed on your
channels.
Use the following steps to create a new one organization or two organization network:
1. Ensure that Docker is running on your machine.

2. Hover your mouse over the Fabric Environments pane and click +, Add Environment.
3. Select Create new from template.
4. Select 1 Org template (1 CA, 1 peer, 1 channel). Alternatively, if you want a larger network or have generated a Private
Data Contract then select 2 Org template (2 CAs, 2 peers, 1 channel).
5. Select V2_0 when asked to choose the channel capability version to use for the network. Alternatively, if you wish to have
v1 channel capabilities select the other option.
This will then take a few minutes to create a local Fabric network including the environment, gateways, and wallets.

Stopping, restarting, tearing down and deleting a preconfigured network
You can stop or restart the preconfigured network while it is running:
1. In the Fabric Environments pane, click the overflow menu.

2. Select Restart, Stop, Teardown to stop, restart, or teardown the container.
Selecting Teardown will completely remove the local Fabric network. Note: This removal results in the loss of the ledger and
world state data.
Selecting Delete will perform a Teardown as well as remove the network from the Fabric Environments pane.
Deploying your smart contract (channel application capability V2)

Smart contracts can be deployed by using the deploy view. This view handles all the deployment steps (install, approve,
commit) which are required by the smart contract lifecycle on channels that are enabled with application capability v2.0 or
higher.
Follow these steps if you have your channel is configured with application capability V2 or higher and a .tar.gz smart contract
package.
To launch the deploy view:
1. Check that you are connected to the network in the Fabric Environments pane.
2. Expand the channel that you want to deploy your smart contract to.
3. Click + Deploy smart contract.
There are three steps to deploying a smart contract by using the deploy view.
Step 1: Choose a smart contract to deploy

1. Use the dropdown to select the smart contract package that you want to deploy.
2. Click Next to proceed.
Step 2: Create definition

1. Provide a name and a version for the smart contract in the appropriate input fields. By default these parameters will be
filled by the name and version of the package.
2. (Optional) Enter a custom endorsement policy in the appropriate input field.
3. (Optional) Select Add file to browse to your collection configuration file if your smart contract uses private data, such as
the Private Data Contract example.
Step 3: Deploy
1. Click Deploy to automatically install, approve, and commit the smart contract on all of the networks peers.
2. (Optional) Use the Perform commit toggle to enable or disable committing this smart contract definition to the channel.
3. (Optional) Click Additional peers to endorse commit transactions to select or deselect any available additional peers that
you need to approve this smart contract definition.
At this point, you smart contract is now "committed" on the channel.If you have changed your smart contract code and then
repackaged it, you can use the deploy view and follow the same steps as above to upgrade the smart contract definition that you
have deployed to the network.

Follow these steps if you have a channel that is configured with the application capability v1.x and a smart contract package that
is in .cds format.

To launch the deploy view:
1. Check that you are connected to the network in the Fabric Environments pane.
2. Expand the channel that you want to deploy your smart contract to.
3. Click + Deploy smart contract.
There are three steps to deploying a smart contract using the deploy view.
Step 1: Choose a smart contract to deploy

1. Use the dropdown to select the smart contract package that you want to deploy.
Step 2: Configure smart contract deployment

1. (Optional) Enter a custom endorsement policy in the appropriate input field.
2. (Optional) Select Add file to browse to your collection configuration file if your smart contract uses private data, such as
the Private Data Contract example.
Step 3: Deploy
1. Click Deploy to automatically install and instantiate (or upgrade) the smart contract on all of the networks peers.
2. (Optional) Enter the function name to call on instantiation/upgrade.
3. (Optional) Enter the function arguments to call on instantiation/upgrade.
At this point, you smart contract is now instantiated on the channel.If you have changed your smart contract code and then
repackaged it, you can use the deploy view and follow the same steps as above to upgrade the smart contract that you have
deployed to the network.
Interacting with your smart contract

After a smart contract is deployed to a channel, you can submit transactions to the functions inside your smart contract by using
the Fabric Gateways pane:
1. Ensure that your smart contract is deployed to a channel, and that you are connected to the network.
2. In the Fabric Gateways pane, expand the Channels dropdown. Click the channel that the smart contract is instantiated or
committed on.
3. Expand the smart contract that you want to interact with. You can find the list of transactions that are listed beneath your
smart contract.
4. Right-click the transaction to submit, and selectSubmit Transaction. For example, if you created and packaged the
example bonds smart contract, click createBond.
5. Enter any arguments that the transaction requires, and press Enter. For example, enter ["bond01","100"] to create your
first bond.
6. (Optional) Enter any arguments that will be submitted as transient data. Transient data is not stored on the channel ledger
in order to keep the data private.
Connecting your applications to the preconfigured network

You can test your client applications by connecting them to the preconfigured network and submitting transactions to your smart
contract.
First, you need to export your connection profile:
1. Ensure that the network is running in the Fabric Environments pane.

2. Right-click on the gateway in the Fabric Gateways panel and select Export Connection Profile.
You can then use the Fabric SDKs and the connection profile to enroll your admin identity by using the usernameadmin and the
password adminpw . You can then use this identity to invoke your smart contract or register and enroll additional users.

Step five: Test a deployed smart contract
You can generate tests for smart contracts that are instantiated or committed on the channels that you connect to. The tests can
be generated as either JavaScript or TypeScript for Node projects, Java for Java projects, or Go for Go projects. Generated tests
can then be run or debugged.
1. Ensure that the smart contract is instantiated or committed on the channel.

2. In the Fabric Gateways pane, right-click the smart contract under the list of channels to generate tests for.
3. Select Generate Smart Contract Tests.
4. Select the language for the test file, either JavaScript, TypeScript, Java, or Go, depending on the smart contract
language. The IBM Blockchain Platform extension installs the required dependencies and builds the test file.
5. Make sure you have either the Node Test Runner extension, Java Test Runner extension or Go extension installed.
After the test file is built, the tests can be run by clicking theRun Tests button in the file.
Step six: Connect to your IBM Blockchain Platform network

You can also use the extension to interact with your network on the IBM Blockchain Platform.
Invoke a smart contract that has been instantiated or committed on your channels
You can download your connection profile from the IBM Blockchain Platform console to build a gateway in theFabric Gateways
pane. You can then use the gateway to invoke the smart contracts that were deployed on your channel.
Open the IBM Blockchain Platform console that is associated with your instance of the IBM Blockchain Platform. Navigate to the
Organizations tab and click the Organization MSP tile for the organization that your client application will interact with. Click
Create connection profile to open a side panel that allows you to build and download your connection profile to your local file
system. Then, create an application identity by using your CA and save the enrollID and secret. Use the following steps to
connect to the IBM Blockchain Platform from VS Code.
1. Open the IBM Blockchain Platform tab.

2. Hover your mouse over the Fabric Gateways pane and click +.
3. Choose Create a gateway from a connection profile.
4. Enter a name for the connection.
5. Enter the fully qualified file path of your connection profile. Your connection should now appear in the connections list
underneath 1 Org Local Fabric.
6. Hover your mouse over the Fabric Wallets pane and click +.
7. Choose Create a new wallet and add an identity from the options. Provide a name for your wallet and your identity.
8. Enter the MSP ID of your organization.
9. Click Select a gateway and provide an enrollment ID and secret option and choose the gateway that you created above.
10. Enter the enrollID and secret of the application identity that you created with the console. A new identity is created in
the Fabric Wallets pane.
11. You can now connect to your instance of your IBM Blockchain Platform network. Click the connection name and select
the name of the wallet that you created. You can also associate the wallet that you created with the gateway by right-
clicking the gateway and selecting Associate A Wallet. This allows the connection to use the same wallet each time when
it connects.
After you connect to the IBM Blockchain Platform from VS Code, you can see the list of channels joined by your organization
peers under the gateway. Under each channel, you can see the list of smart contracts that are instantiated or committed on each
channel and the transactions within each smart contract. You can submit transactions to your network by right-clicking a
function and selecting Submit Transaction and passing the required arguments. You can also generate a test file for the smart
contracts that are instantiated on your channels.
Deploy a smart contract from VS Code

You can also import the IBM Blockchain Platform network into the Fabric Environments pane of the extension. You can then use
the extension to deploy smart contracts on your network.
You can export nodes from your console and then import them from another console. You can use the same process to export
nodes from your console and then import them into the Fabric Environments pane. The easiest way is to use the extension to
automatically discover the console and import the nodes.
1. Navigate to the Settings tab in the left navigation. You can see a section that is calledBulk data management that
contains two buttons. The Export button opens a panel on the right.
2. Check the box to export your identities. You can deselect the other options.
3. Click Export to download the identities to your local file system in .zip file. Extract the file when the download is complete.
You can then import the nodes of your network into the extension.
Importing from IBM Cloud

2. Select Add an IBM Blockchain Platform environment.
3. Select Yes when asked whether to connect to an IBM Blockchain Platform service instance on IBM Cloud.
4. Select Log in with username and password or another method.
5. Enter your IBM Cloud username (email address).
6. Enter your IBM Cloud password.
7. The extension will now try to discover any IBM Blockchain Platform service instances - if you have multiple, select the
instance to import.
8. Enter a name for your environment.
9. Select the CAs and peers that belong to your organization, along with the ordering nodes of your channels, clickOK when
done.
Importing from a Kubernetes cluster not in IBM Cloud

2. Select Add an IBM Blockchain Platform environment.
3. Select No when asked whether to connect to an IBM Blockchain Platform service instance on IBM Cloud.
4. Enter the URL of the IBM Blockchain Platform Console software instance.
5. Enter the User ID for the console instance.
6. Enter the Password for the console instance.
7. Select Proceed without certificate verification, or Cancel if you're planning to add the CA certificates to the operating
systems trusted CA certificate store.
8. Enter a name for your environment.
9. Select the CAs and peers that belong to your organization, along with the ordering nodes of your channels, clickOK when
done.
Tip: In steps 5 and 6, you can alternatively enter an API key and secret that you generate using the IBM Blockchain
Platform REST APIs.
You also need to import your admin identities into the wallet pane and associate them with your nodes. You need to associate an
admin identity with your peers, CA, and an ordering node before you can connect with your network.
1. Click on the environment that you created in the Fabric Environments pane.
2. You can see an Alert sign next to the peer and ordering node. Click on the alert to associate an admin identity with the
node.

3. Select Add a new wallet.
4. Select Create a new wallet.
5. Enter a name for your wallet to identify the orderer or peer admin of your network.
6. Select Add a new identity.
7. Enter name for your peer or orderer admin identity.
8. Select Provide a JSON identity file from the IBM Blockchain Platform and then browse to the admin identity that you
exported from your console. If the identity is the administrator of multiple nodes in your network, you can associate the
identity with multiple nodes.
When you have associated an admin identity with your peers, CA, and an ordering node, you can connect to your network and
use the extension to deploy smart contracts.
Adding wallets and users

Use the following steps to create a new wallet by using a certificate and private key:
1. Hover your mouse over the Fabric Wallets pane and click +.
2. Choose to Create a new wallet and add an identity from the options. Provide a name for your wallet and your identity.
3. Enter the MSP ID of your organization.
4. Choose to add a certificate and private key.
5. If you use a certificate and private key, browse to the certificate and private key.
You can also add new users to the wallets that have already been created:
1. In the Fabric Wallets pane, right-click a wallet and select Add Identity.
2. Provide a name for the identity and an MSP ID.
3. You can upload a JSON file, provide a certificate and private key, or provide an enrollment ID and secret.
If you are connecting to a network on the IBM Blockchain Platform, you can download an identity from your IBM
Blockchain console, either by exporting an identity from your wallet or by enrolling and then exporting an identity
using your Certificate Authority. You can then upload the JSON file directly to VS Code.
If you use a certificate and private key, browse to the certificate and private key.
If you use an enrollment ID and secret, choose the gateway to enroll with and enter the enrollment ID and secret.
Writing powerful smart contracts

As Hyperledger Fabric and the IBM Blockchain platform have evolved, their processes have been made more decentralized and
collaborative. This is why, for example, the old “Kafka” ordering service, in which a single organization owned and managed the
ordering service, was replaced with a “Raft” ordering service in which multiple organizations can administer the ordering service
and contribute nodes.
This same spirit of decentralization and collaboration also drove the development of a new series of processes around installing,
managing, and using smart contracts (these processes are known as the “lifecycle” of a smart contract).
While these new processes are somewhat more elaborate and require more planning and forethought than the "old" lifecycle (in
which a single organization proposed a smart contract instantiation on a channel), the new lifecycle provides many new powerful
and elegant opportunities to satisfy a wider set of business use cases.
This topic will show how these opportunities can be exploited both during development of a smart contract and during its
lifecycle servicing a channel.
What's new in the new lifecycle

In the lifecycle used for Fabric versions before 2.0:
Smart contracts were proposed for instantiation by a single channel member. Organizations could not formally propose
endorsement policies or other smart contract parameters within the context of official Fabric processes.

A “fingerprint” match was required for every smart contract installed on every peer, requiring the smart contract on every
peer on a channel to be exactly the same. This fingerprinting was error prone --- the exact same smart contract could
under certain circumstances produce a slightly different fingerprint, leading to mismatch errors that were difficult to
resolve.
Any change to the smart contract, no matter how minor, required a new package (which must be installed on every peer
and re-fingerprinted) and re-instantiation on the channel.
In the "new" lifecycle used for Fabric versions after 2.0:
Organizations collaborate in the channel-level decision making process regarding smart contracts.
Fingerprint matches are no longer required.
Smart contracts can be updated in some ways without the need for re-instantiation at a channel level.
Different organizations and peers can install smart contracts that only contain code relevant to their business role, yet still
be able to transact with other organizations and peers that contain only the code relevant to their role, while maintaining
deterministic outcomes. More on this later.
Packages and definitions

From a structural standpoint, the biggest change with the new smart contract lifecycle is the logical and physical separation of
the “definition” of a smart contract and “package” of a smart contract.
The latter contains the actual code representing the business logic of the smart contract. When a peer is contacted to “endorse”
a transaction or not, the package contains the code that runs and generates the read/write set.
The definition of a smart contract, on the other hand, contains information like the name, version, and endorsement policy of the
smart contract. These definitions can be proposed by any channel member but must be approved (on a per-org basis) by enough
organizations to satisfy the “lifecycle endorsement policy” of the channel, after which the definition is committed to the channel.
This lifecycle endorsement policy can in theory be anything (including allowing any organization to commit a definition, or just a
single organization), but generally speaking will, in the spirit of collaboration, be something like a “majority of channel admins”.
This separation of the definition (agreed to at the channel level) and the package that’s installed on the peers has powerful
implications for how smart contracts can be written and managed, as we will see.
Taking advantage of the ability for each organization to use a separate package
The elimination of the need for the smart contracts to exactly match their fingerprints opens up exciting new possibilities when
developing smart contracts.
First, to address a natural question: how can results be predictable (or, more to the point, deterministic) if peers in different
organizations aren’t running the same code?
An analogy might help to explain. If two people attempt to multiply two numbers together (33 by 7, for example), one might
decide to multiply 30 by 7 and also 3 by 7 and then add the two resulting numbers together. While the other person might not
use this trick, or choose to use a calculator. It’s not important that both people use the same process, only that they arrive at
the same answer.
The same basic principle is true for different smart contract packages running on different peers producing the same read/write
set, given a set of inputs. As long as the smart contracts running on every peer on a channel produce the same read/write set, it
does not matter if they are running exactly the same code.
But why bother? Why not run the same code?
You certainly can, and it is probably advisable to run the same (or at least similar) code in order to eliminate corner cases that
might emerge if substantially different code is being run against the same data.
However, consider a scenario in which the various organizations on a channel are all executing transactions against a set of data

but have substantially different roles. In this scenario:
Org A: an individual who wants to place an advertisement.

Org B: the owner of the place where advertisements are posted.
Org A should, logically, be allowed to request an ad be placed, and also to query ads. Since their identity would lack the proper
permissions to create an ad, why should the smart contract they install on their peer contain the relevant code for creating an
ad? It’s just unnecessary waste and clutter.
Similarly, Org B would logically be able to query ads and to create them. But they would have no use for the ability torequest an
ad be placed since they already have the ability to create them.
A hypothetical third Org might only need the ability to verify information without actually needing the ability to query or create
information of its own, a popular use case for government entities or other kinds of regulators.
While the desire to reduce unnecessary code clutter is always worthwhile on its own, this ability for different organizations to
have different smart contracts is particularly useful in scenarios when the code to perform certain actions might contain
sensitive information (the location of a server where ads are created, for example).
While the “old” lifecycle did include ways to separate roles through a permissions structure, the ability for different orgs to have
different packages is a more secure and holistic approach to the separation of concerns central to blockchain networks, and
should be taken in account when developing smart contracts to run using the new lifecycle.
In any case, it is a best practice for smart contracts to be tested extensively (preferably on a test channel dedicated to this
purpose) to ensure that all smart contract packages produce the same result, regardless of the underlying code generating that
result. However, keep in mind that as long as an errant result is not reached by enough peers to satisfy the endorsement policy
of a smart contract, the integrity of ledger data will be maintained.
Tip: While the packages themselves can be different, the names of the packages must be identical and conform to the
name given to the smart contract in the definition committed to the channel. If the packages have different names, the
system will believe that the smart contracts do not contain compatible business logic.
Updating smart contracts

Smart contracts can be updated for a variety of reasons. As part of onboarding a new member to a channel, for example, or to
reflect new businesses processes and use cases.
In the onboarding example, it is likely that only the smart contract definition will need to be updated to reflect the new
organization’s ability to endorse transactions (if that will indeed be their role). If the underlying business logic contained in the
package changes, on the other hand, then both the package and the definition will have to change (the latter to reflect a new
version).
While updating the version in the definition is enforced by Fabric and the IBM Blockchain Platform whenever a new package is
installed, the standards adopted by a channel for how those versions are organized are up to the members of the channel.
However, it is recommended to use a consistent semantic versioning pattern.
Tip: In production scenarios, new business logic might be agreed to by the channel members collectively (out of band)
and then be written by a single channel member and passed to the others. If this code will replace custom code you have
in your own smart contract package, make sure you do not overwrite custom variables you already have by replacing the
section of your smart contract without analysis.

Putting it all together
Like everything else about your network, your smart contracts should be tailored for your use case. While a simple smart
contract shared in its entirety among every member of a channel might adequately fulfill your needs, the new lifecycle opens
opportunities for specialization and separation of concerns that didn't exist before and shouldn't be ignored.
For more information about smart contract best practices (as well as how smart contracts relate to the concept of "chaincode"),
see Smart contracts and chaincode.
Smart contract development tooling

While a smart contract can be packaged using the peer CLI, the VS Code extension for developing smart contracts is a highly
useful tool and can be downloaded to your local system.
For more information, see Developing smart contracts with IBM Blockchain Platform Developer Tools.
Installing a package and proposing a definition

For information about how to use the console to install smart contract packages and propose and commit smart contract
definitions on a channel, see Deploy a smart contract using Fabric v2.x.
Best practices for application development

Information previously contained on this page has been refreshed and merged into the Creating Applications tutorial. For the
most up to date recommendations, refer to that tutorial.

Advanced tutorials
For customers who prefer to include intermediate CAs in their network, the IBM® Blockchain Platform offers this configuration
option when you deploy a CA. This tutorial describes the process for creating an intermediate CA.
Intermediate CAs are optional. Because an intermediate CA has its root certificate issued by a root CA or another intermediate
authority, a “chain of trust” is established for any certificate that is issued by all CAs in the chain. Having one or more
intermediate CAs provides added security and allows you to protect your root of trust. This ability to track back to the root CA
not only allows the function of CAs to scale while still providing security, it also limits the exposure of the root CA, which, if
compromised, would endanger the entire chain of trust. If an intermediate CA is compromised, on the other hand, there will be a
much smaller exposure. A key benefit is that after the intermediate CAs are up and running, the root CA can be effectively turned
off, limiting its vulnerability even more.
Another reason to include an intermediate CA would be when you have a very large organization with multiple departments and
you don’t want a single CA to generate certificates for all of the departments. Intermediate CAs provide a mechanism for scoping
the certificates that a CA manages to a smaller department or sub-group. This pattern though incurs significant increase if there
will only be a small number of members in the organization.
As an alternative to deploying multiple intermediate CAs, you can limit the scope of a CA by overriding the CA configuration to
specify available affiliations (similar to departments) instead. When a CA is configured with affiliations, the affiliation of the
registrar must be equal to or a prefix of the affiliation of the identity being registered. See the Fabric CA topic on registering
identities for more details.
The following diagram illustrates how the root CA issues the certificates for the intermediate CA and the intermediate CA then
issues the certificates for the nodes and users in the organization.
Figure 1. Intermediate CA in the network.

No. Because the CA signed certificate cannot be regenerated, you cannot convert an existing CA to become an intermediate CA.
If you did, all of the existing certificates that were issued by the CA would no longer be valid. Therefore, if you want to have an
intermediate CA in your network, you need to create a new CA and configure it to be an intermediate CA during the deployment
process.
Limitations
Currently, IBM Blockchain Platform only supports a single level of intermediate CAs. In other words, an intermediate CA cannot
be a parent server to another intermediate CA.
Process overview
The configuration process begins with the root CA. If one does not already exist, you need to create the root CA and then register
two identities that are needed by the intermediate CA. When you create an intermediate CA you need to provide a JSON that
overrides the default CA settings with the intermediate CA configuration. After your intermediate CA is active, you can use it for
all subsequent identity register and enrollment requests for the organization, and then effectively turn off the root CA. At a high
level, the following steps need to be performed:

1. Deploy a root CA if one does not already exist.

2. Register the intermediate CA admin identity with the root CA.
3. Register the intermediate TLS CA admin identity with the root CA.
4. Export the root CA to a JSON file.
Edit the example JSON override file by providing the root CA TLS signing cert and the intermediate CA identity enroll id and
secrets to the JSON override file.
1. Create a new CA which will serve as the intermediate CA.

2. Provide the intermediate CA admin enroll ID and secret that you registered with the root CA.
3. Provide the CA JSON override file.
After completing these steps, when you create organization MSPs for your peers or orderers, you can point to the intermediate
CA instead of the root CA.
Note: This process can be performed using the console or the APIs, if you are an experienced API user. The overall
process is the same regardless of which approach you choose. For clarity, this tutorial uses the console.

1. Deploy a root CA. Before you can deploy an intermediate CA, a root CA must already exist in your IBM Blockchain
instance. See the Build a network tutorial for instructions on how to create a CA.
2. Register the intermediate CA admin identity with the root CA. In order for an intermediate CA to be able to register and
enroll identities, the intermediate CA admin identity must be registered with the root CA.
Click the root CA tile to open it and clickRegister user.

Enter the enroll ID and secret that you will use for the intermediate CA admin identity. For purposes of this tutorial
we will use icaadmin and icaadminpw, but you can use any values suitable for your use case.
Leave the identity type as client and optionally specify a value for maximum enrollments if you want to limit the
number of times you can generate certificates for this admin identity. Otherwise, you can leave it blank.
On the next panel, because this identity will be for the intermediate CA admin, you need to add the attribute
hf.IntermediateCA and set its value to true. Don't forget to click Add.
Click Register user when you are finished.
3. Register the intermediate TLS CA admin identity with the root CA. Because TLS communications are enabled on the
network, whenever you deploy a CA, a TLS CA is automatically deployed along side the CA, and uses the same endpoint
address. Therefore, you also need to register an identity that will serve as the intermediate TLS CA admin. Repeat the
actions that you performed in the previous step to register the admin identity, but this time specify a different enroll ID and
secret. For purposes of the tutorial, we use itlscaadmin and itlscaadminpw .
4. Export the root CA to a JSON file. Now that you have the intermediate CA admins registered with the root CA, there is one
last piece of information we need: the root CA TLS signed certificate. This certificate is shared with each node in the
organization and is used to secure the communications between the nodes. Therefore, in order for the intermediate CA to
communicate with the root CA, it has to be included in the intermediate CA configuration. To get the root CA TLS signed
certificate, simply export the root CA to a JSON file. Open the root CA and click the Export icon.

Figure 2. Export root CA
Open the downloaded JSON file and locate the value corresponding to the tls_cert element. You will need to
copy and paste the certificate in a later step. It will resemble:
$
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQWtXZ0F3SUJBZ0lRWXZYRUgzUktMUVNiUnZTdnRLWU
JDVEFLQmdncWhrak9QUVFEQWpDQnB6RUwKTUFrR0ExVUVCaE1DVlZNeEZ6QVZCZ05WQkFnVERrNXZjblJvSUVOaGNtO
XNhVzVoTVE4d0RRWURWUVFIRXdaRQpkWEpvWVcweEREQUtCZ05WQkFvVEEwbENUVEVUTUJFR0ExVUJVaHAKVkM1VE5O
VzNqRzJkVVZwUUlkSmEvMWtDSVFEMGE0QWRzazJ0RlhDRFp1RFB0VG5lTkNZWnBDSzMxL2MrUTFLTQozLzVGdEE9PQo
tLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCga1",
Also make note of the value of the api_url in the JSON file. You will use the value of this URL to build the parent
server URL for the intermediate CA. It will resemble:
$ "api_url": "https://nb535a5-rootca.org1Cluster.us-south.containers.appdomain.cloud:7054",
To build the parent server URL, edit the URL and insert the intermediate CA admin enroll ID and secret using the
following format:
$ https://<INTERMEDIATE-CA-ADMIN>:<INTERMEDIATE-CA-ADMIN-PW>@<DOMAIN>:<PORT>
For example:
$ https://icaadmin:icaadminpw@nb535a5-rootca.org1Cluster.us-
south.containers.appdomain.cloud:7054
Save the value of this URL for the next section.

Anytime that you deploy a CA, you can override the default CA settings by pasting a JSON that contains the parameters that you
want to override. Because we are deploying an intermediate CA, we need to override some of the default settings in order to
configure it to be an intermediate CA. For example, you need to configure the intermediate block of the JSON to point to your
root CA as the parent server. Therefore, copy the following text to an editor where you can modify the values:
{
"ca": {
"debug": true,
"registry": {
"identities": [{
"name": "<INTERMEDIATE-CA-ADMIN>",
"pass": "<INTERMEDIATE-CA-ADMIN-PW>",
"type": "client",
"attrs": {

"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "<PARENT-CA-SERVER-URL>",
"caname": "ca"
},
"tls": {
"enabled": true,
}
}
},
"tlsca": {
"debug": true,
"registry": {
"identities": [{
"name": "<INTERMEDIATE-TLS-CA-ADMIN>",
"pass": "<INTERMEDIATE-TLS-CA-ADMIN-PW>",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "<PARENT-TLS-CA-SERVER-URL>",
"caname": "tlsca"
},
"tls": {
"enabled": true,
}
}
}
}
Notice there are settings for both the intermediate CA and the intermediate TLS CA. Replace the following parameters:
<INTERMEDIATE-CA-ADMIN> - with the enroll ID that you specified in Part One, step 2 when you registered the
<INTERMEDIATE-CA-ADMIN-PW> - with the enroll secret that you specified in Part One, step 2 when you registered the
<PARENT-CA-SERVER-URL> - with the value of the parent server that you built in Part One, step 4.
<TLS-CERT-FILE> - (two occurrences) with the value of the tls_cert, the certificate string that you downloaded from the
root CA in Part One, step 4.
<INTERMEDIATE-TLS-CA-ADMIN> - with the enroll ID that you specified in Part One, step 3 when you registered the
intermediate TLS CA admin identity.
<INTERMEDIATE-TLS-CA-ADMIN-PW> - with the enroll secret that you specified in Part One, step 3 when you registered
the intermediate TLS CA admin identity.
<PARENT-TLS-CA-SERVER-URL> - with the value of the parent server URL that you built in Part One, step 4; however you
need to replace the enroll ID and secret with the values that you specified when you registered the admin for the

intermediate TLS CA, in Part One, step 3. Because both the intermediate CA and intermediate TLS CA are deployed to the
same endpoint address, the rest of the URL remains the same as the <PARENT-CA-SERVER-URL>.
Your completed JSON looks similar to:
$ {
"ca": {
"debug": true,
"registry": {
"identities": [{
"name": "icaadmin",
"pass": "icaadminpw",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "https://icaadmin:icaadminpw@nb535a5-rootca.org1Cluster.us-
"caname": "ca"
},
"tls": {
"enabled": true,
"certfiles":
}
}
},
"tlsca": {
"debug": true,
"registry": {
"identities": [{
"name": "itlscaadmin",
"pass": "itlscaadminpw",
"type": "client",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}]
},
"intermediate": {
"parentserver": {
"url": "https://itlscaadmin:itlscaadminpw@nb535a5-rootca.org1Cluster.us-
"caname": "tlsca"
},
"tls": {
"enabled": true,
"certfiles":

}
}
}
}

You've registered the intermediate CA and intermediate TLS CA identities with the root CA and have built the JSON for the CA
override. You are now ready to deploy the intermediate CA.
1. From the Nodes tab, click Add Certificate Authority followed by Create a Certificate Authority.
2. Give your intermediate CA a meaningful name and then provide the intermediate CA admin enroll ID and secret that you
registered with the root CA. For example icaadmin and icaadminpw. You can leave the Advanced deployment options
deselected, none are required for an intermediate CA.
3. On the Summary panel, click Edit configuration JSON (Advanced).
4. Delete the existing content from the Configuration JSON box and paste the JSON that you built in Part Two, then click
Add Certificate Authority.
Tip: It will take a few minutes for the CA to deploy. You'll know it is ready when a green status indicator box is visible on
the tile. Depending on your cluster activity, you might need to refresh your browser for the status to turn green.
Next steps

Your intermediate CA is now operational and can be used to register and enroll identities just like you do with the root CA. See
the topic on Creating and managing identities to learn more.

When you build organization MSP definitions for your peer or ordering nodes, you can now reference the intermediate CA as the
"root CA" instead of your root CA.
Figure 3. MSP using intermediate CA
If you want to learn more about creating MSPs, see Managing organizations.

Because the intermediate CA can process all requests that the root CA handles, you can effectively turn off your root CA by
scaling down the root CA CPU to 0.001 CPU. Taking this action renders the root CA non-functional while in this state. As long as
you don't need the root CA to issue identities or enroll other intermediate CAs, it can be safely scaled down. See the topic on
Reallocating resources for the steps to scale down the CPU. If the root CA is needed later, for example to enroll another
intermediate CA, you can always repeat the steps to scale back up the CPU. The minimum CPU required for a CA to be
operational is 0.1 CPU .
By default, certificates generated by IBM Blockchain Platform CAs expire after one year and peer and ordering node TLS
certificates expire after 15 years. Exactly thirty days before peer and ordering node certificates are due to expire, the platform
automatically attempts to contact the CA and renew the certificates. If the CA is not online, the automatic renewal fails and
enrollment to generate a new certificate needs to be performed manually. If automatic renewal of these certificates is important
for your business, careful consideration should be given to scaling down a root CA or intermediate CA. See the topic on
Certificate expiration and renewal to learn more about the process.

IBM Cloud includes an HSM service that provides cryptographic processing for key generation, encryption, decryption, and key
storage. This document describes how to use that service with the IBM® Blockchain Platform.
While this tutorial focuses specifically on using IBM Cloud HSM, you can learn more about the overall configuration process for
using any HSM that supports PCKS #11 with the IBM Blockchain Platform, see Configuring a node to use a Hardware Security
Module.
When a Certificate Authority (CA), peer, or ordering node is configured to use an HSM, their private key is generated by and
protected inside a tamper resistant HSM device. IBM Cloud HSM is a FIPS 140-2 Level 3 validated, single-tenant device that
implements Gemalto (Luna) HSM. When a CA is configured to use HSM, the CA root private key is stored in the HSM. This is the
key that is used to sign enrollment requests. After a peer or ordering node is configured to use HSM, the nodes are able to sign
and endorse transactions without ever exposing their private key.
Important: Because only the private keys of node identities are secured in the HSM, when you enroll other admin or
client application identities with a CA, their private keys are not stored inside the HSM because they will need their private
key to transact on the network.
Using IBM Cloud HSM

IBM Cloud HSM 6.0 and 7.0 are available in the IBM Cloud catalog. Both versions are supported, however, these instructions
focus on how to configure IBM Cloud HSM 6.0 to work with the IBM Blockchain Platform. If you are using 7.0, it is possible that
some of the commands will differ slightly.
Process overview
This process involves deploying an HSM and configuring a partition as well as deploying an HSM client that you will use to
configure the device. Throughout these instructions you will run some commands from the HSM server and others from
the HSM client. For clarity, we prefix these steps with either or .

Communications between the HSM and client require a Network Trust Link (NTL) -- an encrypted, secure communications
channel between the HSM and client. NTL uses digital certificates that the client and HSM server can use to verify each
other's identity. You will run a command to get the HSM server certificate that allows the client to communicate with the
HSM server. Likewise, you will generate a certificate and private key for the client and then copy them to the HSM server.
After the secure communications are configured, you can register the client with the HSM server and then assign the HSM
partition to the client.
Build an HSM Client image
This process requires Docker to be installed on the machine where the HSM client is running and that you are familiar with the
process for building Docker images. It also presumes you are comfortable with using the Kubernetes CLI to administer your
Kubernetes cluster.
If you are using a Kubernetes cluster on IBM Cloud and IBM Cloud HSM, both services need to be deployed from the same IBM
Cloud account and on the same VLAN. If they are not on the same VLAN, then VLAN spanning must be enabled.
When the entire HSM configuration is complete, it resembles the following diagram:
HSM configured with an HSM client image
Figure 1. An example configuration of an HSM configured with an HSM client image.
The steps in this topic focus specifically on the creation of the Cloud HSM and the HSM Client in the diagram. When you deploy a
CA, peer, or ordering node to use the HSM, you need to provide the label and PIN of the HSM partition. This configuration
assumes you enabled HSM on your Kubernetes cluster when you deployed the service.

1. Provision the HSM and configure it with at least one partition. For example, you can follow instructions for Provisioning
IBM Cloud HSM.
Important: Be sure to record the Label and PIN for the partition. You will need to provide these values later when
you configure a blockchain node to use this HSM partition. Also, save the IP address associated with the HSM
device. We will refer to this value throughout these instructions as <HSM_ADDRESS> .
2. Install the HSM client on your local machine. Make sure the client version that you are running matches the HSM server
version. Record the IP address or fully qualified host name where the HSM client is running. We will refer to this value
throughout these instructions as <CLIENT_ADDRESS> .
Tip: The client runs on AIX, Linux, Oracle Solaris, or Microsoft Windows, but is not supported on MacOS.
In this section you will get the HSM server certificate and create the HSM client certificate-key pair in order for them to be
exchanged.

1. Run the following command using the HSM client to get the server certificate. This certificate enables the client to
communicate with the server.
scp hsm_admin@<HSM_ADDRESS>:server.pem server.pem
Replace
2. Now, add the HSM server to the client configuration by running the following command:
vtl addServer -n <HSM_ADDRESS> -c server.pem
Replace
3. Create the certificate and private key for the client by running the command:
vtl createcert -n <CLIENT_ADDRESS>
Replace
The name of the generated certificates includes the <CLIENT_ADDRESS> . The output of this command looks similar
to:
$ Private Key created and written to:

/usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>Key.pem
Certificate created and written to:
/usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>.pem
4. Copy the client certificate and private key to the HSM server by running the command:
scp /usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>.pem hsm_admin@<HSM_ADDRESS>:.
Replace
1. SSH into the HSM as the admin the HSM server and register the client by runningone of the following commands.
If the <CLIENT_ADDRESS> is the IP address of the client:
client register -client ${CLIENT_NAME} -ip <CLIENT_ADDRESS>
If the <CLIENT_ADDRESS> is the fully qualified host name of the client:
client register -client ${CLIENT_NAME} -hostname <CLIENT_ADDRESS>
Replace
{CLIENT_NAME} with the name of the client. This value can be anything meaningful to you.

<CLIENT_ADDRESS> with either the IP address or fully qualified host name of the client.
2. Because network address translation (NAT) exists between the client and the HSM, we need to disable client source IP
address validation by the Network Trust Link Server (NTLS) upon Network Trust Link Agent (NTLA) client connection.
Disable ip check on the HSM server and then restart the NTLS service on the HSM server by running the following
commands:
ntls ipcheck disable

service restart ntls
3. Assign a partition to the newly created client on the HSM server by running the following command:
client assignpartition -client ${CLIENT_NAME} -partition ${PARTITION_NAME}
Replace
{CLIENT_NAME} with the name that you gave to your HSM client.
{PARTITION_NAME} with the name of the HSM partition you created in Part one, step 1.
You can verify the command worked by running the following command:
$ client show -client ${CLIENT_NAME}
$ ClientID: hsmclient
IPAddress: 10.220.203.73
HTL Required: no
OTT Expiry: n/a
Partitions: "partition1"
Command Result : 0 (Success)
4. Verify the client can connect to HSM server by running the command:
vtl verify
$ The following Luna SA Slots/Partitions were found:

Slot Serial # Label
==== ================ =====
0 500752010 partition1
5. Create a configs folder on the client and then copy the server.pem certificate from Part two, step 1 and the
<CLIENT_ADDRESS>Key.pem and <CLIENT_ADDRESS>.pem files from Part two, step 3 into the folder:
Copy server.pem to configs/server.pem

Copy /usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>Key.pem to configs/key.pem
Copy /usr/safenet/lunaclient/cert/client/<CLIENT_ADDRESS>.pem to configs/cert.pem

To configure HSM on your blockchain network, build an HSM client image as follows below.

operator.

Chrystoki2 settings
files.

Chrystoki2 = {
}
...
LunaSA Client = {
...
...
}
file.

COPY 64 64

gcc \
gcc-c++ \
openssh-clients \
bind-utils \
iputils \
&& cd 64 && \
### Final image ###

look similar to:



<NAMESPACE>
Replace:



$ apiVersion: v1
data:
Chrystoki.conf: ""
cafile.pem: ""
cert.pem: ""
key.pem: ""
kind: Secret
metadata:
name: hsmcrypto

Because the console needs to know the configuration settings to use for your HSM, you need to create a Kubernetes configmap
to store these values. The configMap settings depend on whether you configured a daemon for your HSM or not. In that case, the
IBM Blockchain Platform operator uses the HSM configuration passed in this configmap to get the details about the HSM client
image, such as what image pull secret to use, and the folder mounts that are required. Based on the information provided, when
a CA, peer, or ordering node is deployed with HSM enabled, the operator mounts required the files for the HSM client image. If
you are using a daemon with your HSM, skip ahead to Configure the operator to work with an HSM daemon.
Configure the operator to work with an HSM that does not use a daemon

version: v1
type: hsm
resources:
limits: {}
requests: {}
securityContext:
privileged: false
runAsNonRoot: false
runAsUser: 0
library:
auth:
envs:
mountpaths:
paths:
- key: <KEY>
path: <PATH>
- key: <KEY>
path: <PATH>
paths:
- key: <KEY>
path: <PATH>
- key: <KEY>
path: <PATH>
them individually.
version: v1
type: hsm
library:
auth:

mountpaths:
- mountpath: /hsm
name: hsmcrypto
paths:
- key: cafile.pem
path: cafile.pem
- key: cert.pem
path: cert.pem
- key: key.pem
path: key.pem
- key: server.pem
path: server.pem
secret: hsmcrypto
name: hsmconfig
secret: hsmcrypto
/hsm/cafile.pem .
You have completed the HSM configuration for your blockchain network. Now when you deploy a new CA, peer, or ordering node,
you can configure it to use the HSM that you have configured here. See Configuring a CA, peer, or ordering node to use the HSM
for details.
Configure the operator to work with an HSM daemon
If you configured an HSM daemon, the following sample configuration shows how to configure the openCryptoki zHSM on the
operator. You need to customize the settings according to your daemon.
daemon:
auth:
resources:
limits:
cex.s390.ibm.com/ibp: 1
securityContext:
privileged: false
runAsNonRoot: false
runAsUser: 0
library:
filepath: /hsm/opencryptoki/libopencryptoki.so.0.0.0
auth:
envs:
- name: LD_LIBRARY_PATH
value: /stdll
mountpaths:
- mountpath: /usr/sbin/pkcsslotd
name: pkcsslotd

volumeSource:
emptyDir:
medium: Memory
- mountpath: /var/run
name: varrun
volumeSource:
emptyDir:
medium: Memory
- mountpath: /var/lib/opencryptoki
name: tokeninfo
usePVC: true
- mountpath: /etc/opencryptoki
name: opencryptoki-config
volumeSource:
emptyDir:
medium: Memory
- mountpath: /var/lock/opencryptoki
name: lock
volumeSource:
emptyDir:
medium: Memory
- mountpath: /stdll
name: stdll
volumeSource:
emptyDir:
medium: Memory
type: hsm
version: v1
In the daemon: section, provide the URL of the HSM daemon image that you created. If the image is not hosted publicly,
then you need to create the appropriate pull secret and specify it here as well.
In the library: section, provide the URL of the HSM client image that you created in step two. This is the client that the
CA, peer, and ordering node will use to talk to the HSM daemon. The filepath: is the location of the shared object
library in the image. If the image is not hosted publicly then the user must create the appropriate pull secret and specify it
as well.
In the envs: section, provide the list of environment variables that are required to configure the HSM.
In the mountpaths: section, provide all the necessary artifacts such as config, shared object libraries, shared memory,
etc. that are needed to communicate with the HSM daemon. These settings are vendor-specific as it is your responsibility
to know what directories or files need to be mounted. When the CA, peer, and ordering nodes are deployed, these
mountpaths will be mounted on to their containers along with the HSM client. Most of these mountpaths can be of type
Memory , however, if there are files that need to persist, then set usePVC: true . When set, the operator stores the files in
the mountpath in a persistent medium, by leveraging the PVCs of the CA, peer, and ordering node as the persistent
medium.
What's next
After you have used these instructions to configure your IBM Cloud HSM and build theHSM client image, you are ready to
configure your blockchain nodes to use the HSM. When you create a CA, peer, or ordering node, select the HSM Advanced
deployment option to configure the node to use this HSM.

that takes approximately 0.1CPU and 100M memory.
On the HSM configuration panel, the Use HSM client image toggle is visible. When it is on, you can enter the following values:

In this tutorial, you learn how to use certificates that were generated by an external Certificate Authority (CA) with your IBM®
Blockchain Platform network. After you gather the required certificates for a peer or ordering node, you build a Membership
Service Provider (MSP) definition that is used by your blockchain components.
While it is always possible to use a CA that you create with the console to generate identities, you can also use certificates that
were generated by a CA external to your network, one that is not hosted by IBM, and then build the required organization
Membership Service Provider (MSP) definition that is used by your blockchain components.
Objectives
Gather certificates.
Build MSP definition.
Import MSP into the console.
Create and import the organization admin identity to the wallet.
Deploy a blockchain node.
Before you begin

Install the IBM® Blockchain Platform.
Step 1: Gather certificates

You need to request the following set of certificates from the external CA in X.509 format. When you request the certificates
from your provider, the core requirement for the certificates is that they are ECDSA with Curve P256 and that the private key
uses the PKCS #8 standard. Also when you request the certificates, you need to specify a Node Organizational Unit (OU)
attribute for some certificates as indicated in the Node OU column in the following tables. Certificates can be in the format of a
.pem file or a base64 encoded string.
When you create a peer or ordering node, you need to provide the following four certificates in PEM format. When you request
these certificates from the third-party CA, you need to request a specific Node Organizational Unit (OU) attribute for some
certificates as indicated in the Node OU column.
Node Description Node OU Format

certificates

1. Peer or The public certificate of the node’s identity. "peer" or PEM
ordering "orderer"
node depending
identity on the
certificate node type
2. Peer or The private key corresponding to the public signing certificate. Make sure to keep PEM
ordering this certificate safe, as it can be used to impersonate the node.
node
identity
private
key
3. Peer or The public signing certificate created by your external TLS CA that is used by the PEM
ordering peer or ordering node. The certificate needs to contain the x.509 Subject
service alternative name (SAN) for the peer or ordering nodes. If you are using the Fabric
TLS CA CA client to enroll the identity, you specify the SAN by passing the--csr.hosts
certificate parameter on the enroll command. If the hostname is not yet known, you can
specify a wildcard with the domain name, for example: --csr.hosts '*.ibpv2-
cluster.us-south.containers.appdomain.cloud,127.0.0.1'.
4.Peer or The private key corresponding to the signed certificate from your TLS CA that is PEM
ordering used by the peer or ordering node for secure communications with other members
service on the network.
TLS CA
private
key
Table 1. Node certificates
MSP certificates Description Node OU Format
1. CA root The root certificate of your external CA. You can also provide an base64
certificate intermediate CA root certificate or both.
2. TLS CA root The root certificate of your external TLS CA. You must provide either a TLS base64
certificate CA root certificate or an intermediate TLS CA certificate, you can also
provide both.
3. Intermediate The root certificate of your intermediate CA. You must provide either a CA base64
CA root root certificate or an intermediate CA root certificate, you can also provide
certificate: both.
(Optional)
4. Intermediate The TLS certificate if your TLS certificate is issued by an intermediate TLS base64
CA TLS certificate: CA. Upload the intermediate TLS CA certificate. You must provide either a
(Optional) TLS CA root certificate or an intermediate TLS CA certificate, you may also
provide both.
5. Peer or ordering The signing certificate from your external CA that the admin identity of this "admin" base64
organization peer or ordering service uses.
admin identity
certificate
6. Peer or ordering The private key corresponding to the signed certificate from your external base64
organization CA that the admin identity of this peer or ordering service uses.
admin identity
private key
Table 2. MSP certificates


Replace:
Step 2: Build MSP definition

An MSP definition is the mechanism that allows other members of the blockchain consortium to verify the identity of your nodes
and applications. Because MSPs define an organization, they are required when you create channels, create nodes (to identify
which organization the node belongs to), and validate signatures.
The MSP definition requires that all certificates are encoded in base64 format. If needed, you can convert the contents of a
certificate file, <cert.pem> from PEM format into a base64 string by running the following command on your local machine:
To build the MSP definition, create a JSON by copying the following text and saving it to a file of type JSON:
{
"type": "msp",
"admins": [
"<admins>"
],
"root_certs": [
"<root_certs>"
],
"tls_root_certs": [
"<tls_root_certs>"
],
"enable": true,
},
},
},
}
},
}

provide either a CA root certificate or an intermediate CA certificate. You can also provide both. This is certificates 1 and 3
in the MSP certificates table.
admins: Paste in the signing certificate of the organization admin identity in base64 format. This is certificate 5 in the MSP
certificates table.
This is certificate 2 in the MSP certificates table.
root_certs. This is certificate 1 in the MSP certificates table.
host_url: Specify the URL of the blockchain console where this MSP collects signatures. This is the URL from your browser
minus /nodes. For example, from the Nodes tab, the browser URL is similar to https://d0ddb7-
optools.uss02.blockchain.cloud.ibm.com/nodes. Therefore the host_url would be https://d0ddb7-
optools.uss02.blockchain.cloud.ibm.com.
fabric_node_OUs: Fabric-specific Organization Units (OUs) that enable identity classification. NodeOUs contain
information for how to distinguish clients, peers, and orderers based on their OU. If the check is enforced, by setting
Enabled to true, the MSP considers an identity valid only if it is an identity of type client, a peer, an admin, or an orderer.
An identity should have only one of these special OUs, which are assigned to an identity when it is registered with the CA.
See this topic for an example of how to specify the fabric_node_OU in an MSP in the Fabric Service Discovery
documentation. Or learn more about using Node OUs in Fabric.
This is an example MSP JSON file:
{
"name": "org1msp",
"type": "msp",
"admins": [
"LS0tLS1CRUd...LS0tLQo="
],
"root_certs": [
"LS0tLS1CRUd...LS0tLS0K"
],
"tls_root_certs": [
"LS0tLS1CRUd...LS0y=g"
],
},

},
"enable": true,
},
}
},
"host_url": "https://ibpconsole-console.0defdaa0c51eab4bf04a1-0000.us-
}
Step 3: Import MSP into the console

You have gathered your certificates and built your MSP. Before you can deploy a peer or ordering node, you need to import the
MSP JSON file into your IBM Blockchain Platform console.

Step 4: Create and import the organization admin identity to the wallet
To be able to act as an administrator for an organization, import the identity that is listed in the MSP JSON "admins" section
into your console wallet, including both the public and private key. When you subsequently deploy a peer or ordering node, you
can designate this identity to be the node admin.
1. To import the identity, open the Wallet tab and click Add identity.
2. Give the identity a name.
3. Click Add certificate and browse to the .pem files for the organization admin identity certificate and private key.
Step 5: Deploy a blockchain node

You've gathered all the certificates, created and imported the MSP, and imported the organization admin identity, you are now
ready to deploy a peer or ordering node. The process to deploy a peer and ordering node is slightly different:
Deploy peer
1. From the Nodes tab, click Add peer > Create peer.
2. Provide a name for your peer.
10. From the Peer administrator identity drop-down list, select the organization admin identity that you imported into the

wallet.
11. Review the details on the Summary panel and click Add peer.

1. From the Nodes tab, click Add ordering service > Create ordering service.
2. Provide a name for your ordering service and select the number of ordering nodes that you want to deploy.
10. From the Orderer administrator identity drop-down list, select the organization admin identity that you imported into
the wallet.
11. Review the details on the Summary panel and click Add ordering service.
Note: Instead of creating an ordering service, if you prefer to contribute a single ordering node to an existing Raft ordering
service, open the ordering service and click the Ordering nodes tab. Click Add ordering node, give it a name then and
following the preceding steps.
It takes several minutes for peer and ordering node deployment to complete. When it is successful, you can see a green box on
the node tile in the console. You might need to refresh your browser for the box to turn from gray to green.
Next steps
Your blockchain nodes are ready to be used on the network. In order for the peer to participate on the network, the peer
organization needs to be part of a consortium on an ordering service so that the peer can join a channel.

2. Scroll down to the ordering service and click the tile to open it.
4. From the drop-down list, select the MSP that you imported into the console.
You can now install smart contracts on your peer and join it to an existing channel.
Using Ansible Playbooks

Customers who are interested in automating their IBM® Blockchain Platform network deployments can use Ansible playbooks to
build out their networks.
Target audience: This topic is designed for network creators and system administrators who are responsible for planning and
configuring IBM Blockchain networks on IBM Cloud or on their own Kubernetes cluster and are new to Ansible playbooks.
What is Ansible

Ansible is a powerful open source automation language and in the context of the IBM Blockchain Platform can be used to script
deployments. It is a configuration management tool that automates the network deployment across multiple hosts by the use of
Ansible playbooks. Playbooks declare configurations and orchestrate the steps of any manual ordered process, synchronously
or asynchronously.
Each playbook is composed of one or more plays in a list. The goal of a playbook is to map a group of hosts to some well-defined
roles, represented by actions that Ansible calls tasks. Basically, a task is simply a call to an Ansible module.
Ansible Content Collections, or simply collections, are the mechanism for distributing, maintaining, and consuming the
automation. Combining multiple types of Ansible content (playbooks, roles, modules, and plug-ins) into a collection, adds
flexibility and scalability for automating your blockchain network deployment. The open source collections are published in
Ansible Galaxy where they can be freely downloaded. Check out their documentation for more education.
IBM Blockchain Platform offers an Ansible collection that includes the pertinent roles, modules, and documentation for rapidly
deploying, replicating, and tearing down blockchain networks in a reproducible fashion.
The Ansible collection includes a set of playbooks that automate the tasks that you would otherwise perform from the console
UI or by using the APIs, for example deploy a Certificate Authority (CA). But the playbooks are more robust than just that. The
playbooks automate a logical series of tasks that you would repeatedly perform in the console, for example create a CA, register
identities, create an organization MSP definition, and create a peer. And all of these steps can be performed by running a single
playbook.
Tip: This tutorial series is designed for users who are unfamiliar with how to use Ansible playbooks. Experienced Ansible
users can go directly to the collection documentation to get started.

The IBM Blockchain Platform Ansible collection uses the IBM Blockchain Platform REST APIs. It includes an entire set of
playbooks that can be used to deploy your peer, Certificate Authority (CA), and ordering service nodes, create organizations,
identities, channels, and deploy smart contracts. And when you need to start over, there are scripts for tearing it all back down.
These playbooks will run on your blockchain network that is running on IBM Cloud or on your own Kubernetes cluster where the
IBM Blockchain Platform is installed.

The Ansible playbooks include a set of modules that you can use to automate the deployment of your nodes, registering of
identities, channel creation, and smart contracts installation and instantiation.
Deploying your blockchain network After you deploy the IBM Blockchain Platform to a Kubernetes cluster on IBM Cloud,
or on your supported Kubernetes distribution, there are three ways to build your network. To understand the benefit of
using the Ansible playbooks, we compare the options:
1. Deploy your nodes and configure your network manually using the console user interface.This option is most
useful for getting started and learning about the platform and how the console works. It requires stepping through
multiple panels to configure all the settings for your nodes, organizations, channels, and smart contracts.
2. Use the IBM Blockchain Platform REST APIs to build your network. This option is for advanced users who want to
leverage the available REST APIs, often in conjunction with the Hyperledger Fabric APIs, to set up and administer
their blockchain network. Configuration is done through editing API parameters. Because the IBM Blockchain
Platform APIs are mainly for create, retrieve, update, and delete operations on a node, you may need to also learn
and use the Hyperledger Fabric APIs for some tasks.

3. Use the IBM Blockchain Platform Ansible Collection. After you are familiar with the process to set up the various
nodes, organizations, channels, and smart contracts, you might want to automate the process. The Ansible
playbooks provide a simple, straightforward, way to build and deploy a reproducible network. For getting started, a
set of scripts is provided that stitches the relevant playbooks together into a single executable shell script of
deployments to perform on your network. Configuration is done through editing .yml files. The Ansible playbooks
also automate some of the tasks performed by the Fabric APIs, such as creating a channel, joining a peer to a
channel, and installing and instantiating smart contracts. Even more, there are playbooks available for tearing down
the configuration so you can reset your network as needed. This option is a great option for setting up networks for
POCs, demos, development, and test networks.
The Ansible playbooks provide an easy-to-use, automated process to replicate your blockchain networks on-demand.
All components that are deployed with the playbooks are also visible in the console where you can interact with
them as normal and govern your network.

Console wallet identities - When you use the Ansible playbooks to deploy blockchain nodes, the identities that are required to
operate the nodes in the network are generated for you. Don't worry, you have the opportunity to configure the node enroll ID
and secrets. But the identities aren't added to the console wallet in the browser. That is a simple manual import step that you
need to perform after the playbooks finish and is described in the tutorial on using the playbooks to build your network.
Getting started
There are multiple ways to install the Ansible collection. One option is to install all of the prerequisite software locally, which can
be cumbersome for first-time Ansible users. Another simpler option is to run the playbooks from a Docker image. Because using
a Docker image completely bypasses the need for the prerequisite setup (the prereqs are part of the Docker image), this
approach is by far the simplest option and is the process that we use throughout these tutorials. This option does require that
you install Docker before proceeding. To determine whether Docker is installed, run the command docker --version . If it is
installed, you'll see something similar to:
$ ```
Docker version 18.09.2, build 6247962
```
If you do not have Docker installed, see install Docker to download and install it. You can also check out the Docker site for
more education and documentation.
Advanced users can review the Ansible collection documentation for other installation options.
Next steps
After the image is successfully built, it can be used to run a playbook. To get started with the playbooks see Building an IBM
Blockchain Platform network using Ansible playbooks if you already have an existing instance of the IBM Blockchain Platform
deployed and want to use the Ansible playbooks to deploy your network components.

Ansible is an open source technology, therefore the Ansible playbooks are not officially supported by IBM. For support related to
the usage of the IBM Blockchain Platform and Ansible playbooks open an issue in the GitHub repository

Customers can use Ansible playbooks to automate the setup and tear down of IBM® Blockchain Platform network components.
Target audience: This topic is designed for system administrators or operators who are responsible for creating or removing
components in an IBM Blockchain Platform network and are new to Ansible playbooks.
In this tutorial, we gather the connection information to your console and demonstrate how to use that information to configure
the playbooks. The playbooks group and automate common network deployment tasks so that you can bypass manually
configuring your network from the console. We teach you how to run an individual playbook and then how to run them
sequentially from a script. In just a few minutes, you can deploy an entire set of blockchain components that are ready to
process transactions on your IBM Blockchain Platform network.
The Ansible scripts can be used to build the following network that includes two organizations (Org1 and Org2) that each
contains one peer and an ordering service with a channel joined by both peers. It's a simple process to customize the playbooks
with your own component or organization names. They can also be used to deploy smart contracts on the channel. And as you
become more proficient, you can use the playbooks to build additional organizations, peers, ordering services, and channels
according to your use case.
Figure 1. Network components created by the Ansible playbooks
Prerequisites
Before using the playbook, you need to complete the following steps:
Link an instance of the IBM Blockchain Platform to your Kubernetes cluster on IBM Cloud.
Review the topic on Getting started with Ansible playbooks on the IBM Blockchain Platform.
Install Docker.

After you deploy an IBM Blockchain Platform service instance, you need to gather the connection information for the console.
When your cluster is running in IBM Cloud, you need to create service credentials for the IBM Blockchain Platform service
instance. The Ansible playbooks use the IBM Blockchain Platform REST APIs to interact with the console. The REST APIs use the
API key (api_key) and API endpoint (api_endpoint) to authenticate with the server and retrieve a Cloud Identity and Access
Management (IAM) access token. The values of the api_endpoint and api_key for the console can be found in the generated
service credentials.
Follow instructions on retrieving service credentials in IBM Cloud to gather these values now that are used with the playbooks
later in this topic.

The Ansible collection source code is available in a GitHub repository. You need to clone the Ansible collection to your local
system so that you can run the playbooks and customize them according to your use case. From the command line on your local
system run the command:
$ ```
git clone https://github.com/IBM-Blockchain/ansible-collection.git
```
We'll explore the contents of this collection in the next section.

After you clone the Ansible collection to your local system, open the ansible-collection directory and navigate to the
tutorial folder and take a moment to review the contents.
$ ```bash
cd ansible-collection/tutorial
```
The first thing that you notice is that the playbook .yml files are numbered. Because the playbooks build on each other, the
numbers help you understand the order that they should be run. When you want to change some of the configuration properties,
you can edit the .yml files and insert your own custom values, for example, if you want to customize a node name or use a
different enrollment ID. Each playbook includes either a role or a task. A role includes a set of tasks that in turn call the
associated modules that submit the requests to your cluster.
The next thing to notice is the set of variable files ordering-org-vars.yml (Ordering Org), org1-vars.yml (Org1), and
org2-vars.yml (Org2) that define the IBM Blockchain Platform console connection details for each organization. These
variable files are used by the playbook when you run it. This means that before you run a playbook, if it uses a variable file, you
need to customize the associated variable file with the connection information that you gathered in the previous step. When a
playbook requires a variables file, it is included in the playbook .yml file.
The variable files include the following four fields that define your connection information to your console:
$ ```
api_endpoint: https://ibp-console.example.org:32000
api_authtype: ibmcloud
api_key: xxxxxxxx
api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
You need to replace the fields with the following values:
api_endpoint - Set this value to the api_endpoint from your service credentials.
api_authtype - Because your cluster is in IBM Cloud, this value needs to be set toibmcloud.
api_key - to the value of api_key contained in the service credentials.
api_secret - This value is not used for clusters in IBM Cloud. No value is required here.
Refer to Gather console connection information for instructions on how to get the service credentials.
You can go ahead now and modify the ordering-org-vars.yml (Ordering Org), org1-vars.yml (Org1), and org2-vars.yml
files with your console connection information.
There is also a common variables file, common-vars.yml . You do not need to edit this variable file right now. This file contains
variables that are used by multiple organizations, for example the name of the channel that will be created, and the name of the
smart contract that will be deployed. Later, when you are ready to create your own custom network you will want to modify these
values according to your business use case.
Note: These instructions assume that you have installed Docker) in order to use the Ansible playbooks. If you have
installed all of the prerequisites locally on your system instead, you can refer to the Ansible documentation for
instructions on how to run the playbooks.
1. We use a Docker command to run the first playbook that creates an ordering organization that is namedOrdering Org,
with a certificate authority named Ordering Org CA, and finally a single node ordering service named Ordering Service. If
you have not already, go ahead and modify the console connection variables inside the ordering-org-vars.yml by

using the instructions from the previous section. You are now ready to run an Ansible playbook from Docker.
The following command invokes the 01-create-ordering-organization-components.yml playbook.
docker run --rm -v <FULLY-QUALIFIED-PATH-TO-PLAYBOOKS>:/playbooks ibmcom/ibp-ansible ansible-

playbook /playbooks/<PLAYBOOK>.yml
where:
--rm tells Docker to remove the container when the command completes.
-v <FULLY-QUALIFIED-PATH-TO-PLAYBOOKS> is used to mount the tutorial folder into the Docker container.
Replace <FULLY-QUALIFIED-PATH-TO-PLAYBOOKS> with the fully qualified path to where the tutorial folder
resides on your local system. When you run the command from the tutorial folder you can replace this value with
$PWD.
ibmcom/ibp-ansible represents the tag of the Docker image that is published by IBM.
<PLAYBOOK> is used to designate which playbook to run.
For example:
$ cd tutorial
docker run --rm -v $PWD:/playbooks ibmcom/ibp-ansible ansible-playbook /playbooks/01-
create-ordering-organization-components.yml
While the command is running, you see output from each task. You can safely ignore the following warning:
$ [WARNING]: provided hosts list is empty, only localhost is available. Note that the
implicit localhost does not match 'all'`.
When the playbook is finished, in the PLAY RECAP section, you see output similar to:
$ PLAY RECAP *********************************************************************

localhost : ok=7 changed=5 unreachable=0 failed=0 skipped=1
rescued=0 ignored=0
If the playbook completes successfully, you should see failed=0 . Go ahead now and log in to your console to
confirm that Ordering Org CA, Ordering Org organization, and Ordering Service was created.
2. The same instructions can be repeated for the next playbook, 02-create-endorsing-organization-components.yml .
This playbook creates an endorsing organization named Org1, with a certificate authority named Org1 CA, and then a peer
named Org1 Peer. When you open the playbook, notice in the comments that this playbook uses a different variables file
org1-vars.yml . Edit that file with your console connection information. And then run that playbook:
docker run --rm -v $PWD:/playbooks ibmcom/ibp-ansible ansible-playbook /playbooks/02-create-

endorsing-organization-components.yml"
Again, if you check your console, you can see that the Org1 CA, Org1 organization, and Org1 Peer was created.
3. You can continue running each playbook individually in the list to stand up a basic network that contains an ordering
service, two peer organizations, two peers, and a channel. The playbooks also install smart contracts on the peers and
instantiate them on the channel.
Check out this topic on Exploring the playbooks for more information about how each playbook works.
By now, you are probably interested in scripting these commands together to stand up or even tear down the components. The
next section walks you through how to do that.

At this point you've experienced how powerful the Ansible playbooks can be for programmatically deploying network
components, creating channels and installing and instantiating smart contracts. But it is likely that you will want to script them
together to build reproducible networks. That's why in the tutorial folder a set of scripts are provided that run groups of
playbooks together in a logical order:
build_network.sh - This is a script that runs a set of playbooks that create an entire simple network, the same one that
can be created if you manually build the network by completing the Build a network tutorial. When you call the script with
the build option, it configures a single node ordering service, a peer organization and a peer. It installs theFabCar
smart contract on the peer, creates a channel and joins the peer to the channel. If you run the script with the destroy
option it removes all of these artifacts from your cluster. For details, see Building a network.
join_network.sh - Run this script when you want to join a peer organization to an existing channel. For more details see
Joining a network.
deploy_smart_contract.sh - This script can be used to install a smart contract on one or more peers in your
organization and instantiate it on a channel. For more details, see Deploying the smart contract.
Before running any script, you need to update the console connection settings in the ordering-org-var.yml , org1-
vars.yml , and org2-vars.yml files. Go ahead and try out the build_network.sh script by running the following Docker
command from your tutorial folder:
docker run --rm -v "$PWD:/tutorials" ibmcom/ibp-ansible /tutorials/build_network.sh -i build
Notice that the playbooks will run even if the artifacts that you are deploying already exist. In that case, you can see in thePLAY
RECAP status that changed=0 , meaning the playbook detected that the node exists and did not try to re-create it. You can also
run the build_network.sh with the destroy option to remove all the nodes and metadata that were created when you ran
the build_network.sh script with the build option. Give it a try now by running the command:
docker run --rm -v "$PWD:/tutorials" ibmcom/ibp-ansible /tutorials/build_network.sh -i destroy
Hints and Tips

Tip Action
Increasing Some clusters perform faster than others. The scripts use a default wait timeout of600 seconds, which is
the wait sufficient for most environments. The wait timeout represents the maximum amount of time the playbook
timeout waits for the underlying transactions to complete before it logs a failure. If you need to increase the
timeout, open the associated variables file (ordering-org-vars.yml, org1-vars.yml, or org2-
vars.yml) and modify the value of the wait_timeout: parameter.
Customizing The playbooks use the organization names that are defined in the common-vars.yml file. When you are
organization ready to configure your own organizations, you can edit the file and specify the preferred organization
names names for your network.
Customizing The default ordering service name is defined in the common-vars.yml file in the ordering_service_name
the name of parameter. Edit this value to specify the preferred name of the ordering service.
the ordering
service
Adjusting By default, the 01-create-ordering-organization-components.yml playbook is configured to create a

how many single node ordering service. If your cluster has the resources to support additional ordering nodes in the
ordering ordering service, you can modify how many ordering nodes are created when the ordering service is
nodes are deployed by editing the 01-create-ordering-organization-components.yml playbook and specifying
created for the number of ordering nodes that you want to deploy in the ordering_service_nodes: parameter.
an ordering
service

Adjusting You can customize the resources that are allocated to a node by editing theresources block of its
node associated module. For example, to modify the CPU and memory that is allocated to a CA node, navigate
resources to your clone of the certificate_authority module on your local system. Scroll down to theresources
section and modify the values that are assigned to cpu and memory. Likewise, you can modify peer
resources in your clone of the peer module or the ordering service resources in the ordering service
module.
Using your By default, the 19-install-chaincode.yml and 20-instantiate-chaincode.yml playbooks use the
own smart Fabric 2.0 smart contract lifecycle with the FabCar sample smart contract. When you are ready to deploy
contract your own smart contract, you need to:
1. Include the smart contract package in the tutorial directory and name it using the format
<SMART-CONTRACT-NAME>@<VERSION>.tar.gz.
2. Refer to your smart contract by replacing the value of the smart_contract_base_name: and
smart_contract_version: parameters in the common-vars.yml file.
Using your When the playbooks deploy a node, it uses the enroll IDs specified in the 01-create-ordering-
own enroll organization-components.yml and 02-create-endorsing-organization-components.yml files. The
ID and associated enroll secrets are provided in the corresponding variable files ordering-org-vars.yml, org1-
secrets vars.yml, and org2-vars.yml. You can customize the values of the enroll ID and secrets in these files
according to your needs.
Table 1. Hints and tips for using the Ansible collection
Next steps
Now that you have used the playbooks to deploy your components or even scripted the deployment of your network, you can
continue to use the console UI to interact with and govern your blockchain components. You will notice right away that the
Ansible scripts do not associate an identity with the nodes that it deploys. If you plan to operate the nodes from the console, you
need to use a manual process to upload the node identities to the console wallet and associate them with the nodes. The
generated node identities are JSON files and are stored in the tutorial folder.
The following table lists the names of the JSON files that contain the identities that are generated by the build_network.sh
script with the build option or the join_network.sh script for the case of Org 2. If you customized organization names inside
the playbook .yml files, it is possible that your JSON files will be named differently. In order to operate the nodes from the
console, you need to import all of the generated identities into the console wallet by using the following process:
1. Navigate to the console wallet and click Add identity.

2. Click the Upload JSON tab and browse to the generated identities in the tutorial folder and click Add identity.
3. Repeat these steps for each identity file in the following table.
Ordering Org Org1 Org2
Organization Admin Ordering Org Admin.json Org1 Admin.json Org1 Admin.json
Organization CA Admin Ordering Org CA Admin.json Org1 CA Admin.json Org2 CA Admin.json
Table 1. File names of organization admin identities
Important: When you run the build_network.sh script with the destroy option, all of the nodes and associated
metadata are removed from your cluster, but any identities that you manually imported into the console wallet are not
removed. Before you run the build_network.sh script again with the build option, you need to manually remove each
identity, by opening it in the wallet and then clicking Remove identity.

Using the wallet identities from the preceding table, you can now follow the steps in the following table to associate identities for
each node type.
Associate an identity with CAs

Open the Ordering Org CA and click Associate identity.
Click the Existing CA tab and select the Ordering Org CA Admin.
If you created the endorsing organizations for the peers, repeat these steps for theOrg1 CA and Org2 CA nodes,
associating the Org1 CA Admin and Org2 CA Admin identities respectively.
Table 2. CA identities
Associate an identity with peers

Open the Org1 Peer and click Associate identity.
Select the Org1 Admin from the drop-down list and click Associate identity.
If you created the second endorsing organization (Org2) for the peers, repeat these steps for theOrg2 Peer by
associating the Org2 Admin identity.
Table 2. Peer identities
Associate an identity with the ordering service

Open the Ordering Service and click Associate identity.
Select the Ordering Org Admin from the drop-down list and click Associate identity.
Table 2. Ordering service identities
Summary
Congratulations. You have used the Ansible playbooks to configure IBM Blockchain Platform components on your cluster. You
know how to run a playbook individually and have some sample shell scripts that show how to run the playbooks together to
build a reproducible network and tear it back down. You can explore further by building your own playbooks that call the Ansible
modules or build your own custom scripts according to your network use case.

IBM Log Analysis
IBM Cloud includes the IBM Log Analysis service which is useful for viewing and parsing the logs of your IBM® Blockchain
Platform nodes and smart contract containers.
This tutorial describes how to configure IBM Log Analysis service to work with your IBM Blockchain Platform service instance.
First, you need to configure cluster-level logging for you Kubernetes cluster. Then, you can access the Open Dashboard from the
Logging tab of the Observability dashboard in IBM Cloud.
Step one: Configure cluster-level logging

You need to deploy an instance of the IBM Log Analysis service in your IBM Cloud account. Complete the steps in the Managing
Kubernetes cluster logs with IBM Log Analysis tutorial. If you are using an OpenShift cluster on IBM Cloud you will need to
configure the IBM Log Analysis agent. Refer to these instructions.
Step two: View the logs for your IBM Blockchain Platform nodes
Using the IBM Log Analysis service makes viewing your IBM Blockchain Platform node logs simple. The search input box located
at the end of the IBM Log Analysis page can be used to filter the logs. See the following examples.
View node logs

When you deploy a peer, Certificate Authority (CA), or ordering node, a new pod is created in your Kubernetes cluster. You can
use the name of the pod to filter the logs by node. For example, to view the logs of a peer node simply add the text pod:
<pod_name_of_peer_node> to the search input box, replacing <pod_name_of_peer_node> with the name of the peer node
pod. The pod name of your node can be obtained by using kubectl commands such as kubectl get pod , or it is visible in your
Kubernetes dashboard.
kubectl get po
The output looks similar to: NAME READY STATUS RESTARTS AGE ibp-operator-6558fdc54f-c5zmn 1/1 Running 0 65m org1ca-
74b8f49fb6-z8gvx 1/1 Running 0 60m peerorg1-5765d88c85-jglk2 4/4 Running 0 25m
In the IBM Log Analysis search box, prepend the name of the pod with the text pod: such that the resulting search string in the
tracking dashboard resembles:
pod:peerorg1-5765d88c85-jglk2
This same process can be used to view the logs of ordering nodes, peers and CAs. Simply add the pod name of the node to the
search bar as shown in the following screenshot:
Figure 1.Filtering logs by node
If you are not getting any results, you might need to filter on your namespace for the blockchain nodes to be visible in the
Kubernetes dashboard. To find the namespace, open any Certificate Authority tile in your blockchain console and click the Info
and usage tab. View the value of the API URL. For example: https://nf85a2a-znorg10524.ibpv2-cluster.us-
south.containers.appdomain.cloud:7054 .
The namespace is the first part of the URL beginning with the letter n and followed by a random string of six alphanumeric
characters. So in the example above the value of the namespace is nf85a2a . Then run the kubectl command:

kubectl get po -n <NAMESPACE>
Replace <NAMESPACE> with the value of your namespace. For example:
kubectl get po -n nf85a2a
The output looks similar to: NAME READY STATUS RESTARTS AGE ibp-operator-6558fdc54f-c5zmn 1/1 Running 0 65m org1ca-
74b8f49fb6-z8gvx 1/1 Running 0 60m peerorg1-5765d88c85-jglk2 4/4 Running 0 25m
In the IBM Log Analysis search box, prepend the name of the pod with the text pod: and the value of the namespace . The
resulting search string in the tracking dashboard would then be:
pod:nf85a2apeerorg1-5765d88c85-jglk2
In this case, nf85a2apeerorg1-5765d88c85-jglk2 represents the name of the peer pod.
View smart contract logs

The process to view the logs for a smart contract is similar to how you view your node logs but varies depending on whether your
peer is running a Fabric v1.4 or v2.x image. The Fabric version that the peer is running is visible when you click on a peer node in
the console:
Figure 2.How to find peer fabric version
Hyperledger Fabric v1.4 peer image

When your peer is using the Hyperledger Fabric v1.4 image, additional strings are required in the search input box.
Just like when you view node logs, you filter on the pod name, but it needs to be the name of the peer pod where the
smart contract is running.
Smart contracts run in a dind container in the pod, but the logs are forwarded to thechaincode-logs container which is
of type fluentd. Therefore, to filter the logs to only include the smart contract events, you need to include app:fluentd
in the search input box.
Finally, you can append the name and optionally the version of the smart contract,marbles 1.0.0.
The full search string, including the namespace, would be similar to the following example:
pod:n4c817fpeer1org1-55885d5666-zq55t app:fluentd marbles 1.0.0
Figure 3.Filtering logs by smart contract
Hyperledger Fabric v2.x peer image

In order to filter on the smart contract logs, you need to provide the name of the pod where the smart contract is
running. Complete the following steps to get the name of the smart contract pod:
Find your cluster namespace
If you don't already know it, you need to find your Kubernetes cluster namespace. From the console, open any CA node and click
the Info and Usage icon. View the value of the API URL. For example: https://n2734d0-soorg10524.ibpv2-cluster.us-
followed by a random string of six alphanumeric characters. So in the example, the value of the namespace is n2734d0 .
Find the smart contract pod

Next, use kubectl commands to get a list of all of the chaincode pods running in your cluster:
$ NAME READY STATUS RESTARTS

AGE LABELS
chaincode-id=myjavacc-1.1,peer-id=org1peer1
chaincode-id=mynodecc-1.1,peer-id=org1peer1
Find your smart contract pod by examining the associated chaincode-id that contains the smart contract name and version.
Then in IBM Log Analysis, to view the logs for the myjavacc version 1.1 smart contract, you can enter the pod name in the
search bar as follows:
pod:<SMART_CONTACT_POD>
For example:
pod:chaincode-execution-0a8fb504-78e2-4d50-a614-e95fb7e7c8f4
Summary
Congratulations. In this tutorial you learned how easy it is to use IBM Log Analysis to view the logs for your blockchain nodes and
smart contracts. To learn more about monitoring your network, check out the tutorial on using IBM Cloud Monitoring with your
blockchain network.
IBM Cloud Monitoring

IBM Cloud includes the IBM Cloud® Monitoring service which is useful for monitoring your IBM Blockchain Platform peer,
orderer, and certificate authority (CA) nodes, and smart contract containers.
The tutorial provides a set of instructions for getting started with using the IBM Cloud Monitoring to monitor the resource usage
of peer, CA, and ordering service nodes. These instructions include how to configure the IBM Cloud Monitoring service to monitor
your existing IBM Blockchain Platform service instance and starts with creating an instance of IBM Cloud Monitoring in IBM
Cloud. Then, you can configure the Open Dashboard to monitor your blockchain components. To learn more about the IBM Cloud
Monitoring service and what it offers, see the IBM Cloud Monitoring documentation.
Monitoring the resource allocation for your blockchain nodes is a key part of operating a blockchain network. You are responsible
for monitoring your resource usage and taking steps to address resource contention. The IBM Cloud Monitoring is a useful tool
for monitoring your network, but you can use any tool you prefer.
This tutorial uses the Free 30-day Trial version of the service, but more advanced features are available in theGraduated tier
which you can explore if your requirements merit.
Note: It is recommended that the IBM Cloud Monitoring instance reside in the same region as your IBM Blockchain
Platform instance. See Enabling Platform Metrics for more information.

Before you begin
You should already have an IBM Blockchain Platform service instance deployed and configured with peers, CAs, and ordering
service nodes running and ready for monitoring before you attempt this tutorial.
Step one: Provision an instance of the IBM Cloud Monitoring service

Deploy an instance of the IBM Cloud Monitoring service in your IBM Cloud account. Complete the steps in the Monitoring getting
started tutorial tutorial.
Tip: After you provision the monitoring service, if you click Edit sources in the Monitoring tab, a curl command is provided
to easily configure monitoring of your Kubernetes cluster. Simply login to your Kubernetes cluster from the CLI and run
the curl command to configure the monitoring service for your cluster. In Step two below, your monitoring instance
should be ready to go. If the curl command fails, ensure that your kubectl version is 1.14 or higher.
Step two: Configure the Open Dashboard for monitoring your IBM Blockchain Platform nodes
After you have provisioned the IBM Cloud Monitoring service, clickView Open Dashboard from the Monitoring tab of the Open
Dashboard in IBM Cloud.
1. On the Welcome to IBM Cloud Monitoring panel click Next.

2. Choose Kubernetes | GKE | OpenShift as the installation method.
3. If you have not already configured the instance, you can do so now by following the instructions. Otherwise after the
service is provisioned and you can click Go to next step! then Let’s get started to launch the Open Dashboard.
Step three: Create a new dashboard

A good place to start monitoring your IBM Blockchain Platform is the Dashboards tab where you can copy and tailor default
dashboards according to your monitoring requirements. A dashboard shows groups of metrics that report on the health,
performance, and state of your infrastructure, applications, and services for a single host or a group of hosts. Dashboards offer a
specialized insight into network data, application data, topology, services, hosts, and containers. Use dashboards to monitor your
infrastructure, applications, and services.
The following sets of instructions are based on the default dashboard named Overview by Container that provides a good set of
widgets for getting started monitoring the resource allocation of your nodes. Each dashboard includes a set of preconfigured
panels. We can copy the dashboard and then customize the panels for the node type that we want to monitor.
Copy the Overview by Container dashboard

1. Click the Dashboards tab in the IBM Cloud Monitoring web UI.
2. Under the My Dashboards twistie, click Overview by Container.
3. In the top right corner of the panel, click Options , then Copy Dashboard.
4. Give the Dashboard a name, Blockchain Operations - Peers and click Copy and Open.
5. Now we need to filter the data on the page to only include the peer containers. In the top right corner, clickEdit Scope.
6. Click the Everywhere drop down list and specify the filter container.name contains peer.
7. (Optional) If your IBM Cloud account includes multiple Kubernetes clusters, you should also filter by cluster. Add an
additional cluster filter, by selecting agent.tag.cluster in and then select your cluster name. Click Save.
Next, we will segment the data in the panels by peer containers.
Configure panels to view CPU and Memory usage

Now the data on the dashboard is filtered to only show data from the peers in your cluster. Let's drill in a little deeper to see the

resource usage by peer container.
1. Click the CPU % chart and then click the pencil Edit Panel icon. In this panel you can tailor the graph type and even
change the metric. But we just want to see the data broken out by peer container, assuming you have more than one peer
in your cluster.
2. In the Segment by drop down list, select the kubernetes.deployment.label.name which is the segmentation choice
that causes the chart data to be broken down by each peer container in your cluster. Click Save.
3. Repeat this process for the Memory Usage % panel. Now you can monitor the CPU and Memory used by each peer
container.
At this point you can edit the panels and play with the different chart types to see different representations of the data.
Configure panels to view disk usage

Storage usage is also interesting to monitor but is not part of the default dashboard panel set. We need to add a new panel to
dashboard to monitor disk usage.
1. Click the + sign above the Edit Scope button in the top right corner.
2. Give this new panel a title, Disk space used %.
3. Select fs.used.percent from the Metrics drop-down list.
4. In the Segment by drop down list, select kubernetes.deployment.label.name and click Save.
5. Hover your mouse over the data in the generated graph and a pop-up window is displayed that shows the average disk
space percentage used by each peer container.
At this point you have configured panels to display the percentage of CPU used by each peer container, the percentage of
memory used by each peer container, and the percentage of disk space used by each peer container. You can drag the panels up
and down on the dashboard, and delete any panels that are not interesting to you.
Figure 1. Peer dashboard in IBM Cloud Monitoring
Create dashboards for the CA and ordering nodes

When you are satisfied with your peer dashboard, you can simply replicate it, using the Copy Dashboard menu item on the
Options menu. Give the dashboard a new name, for example Blockchain Operations - CAs or Blockchain Operations - Ordering
nodes. Then, edit the scope of the new dashboard to be either container.name contains ca or container.name contains
orderer respectively.
Step four: Configure alerts to monitor resource usage

Now that you have configured monitoring of your peer, CA, and ordering nodes, the final important step is to configure alerts in
IBM Cloud Monitoring so that a notification is triggered when a specified condition is met. You can trigger an alert notification via
email, slack, PagerDuty, Webhooks, OpsGenie, and VictorOps channels. First configure the notification channel and then define
the alert triggers.
1. Configure your preferred notification channel by clicking on your user icon followed by Settings.
Figure 2. IBM Cloud Monitoring settings panel
When you subsequently click Notification Channels > Add Notification Channel you are able to select how you want to be
notified when an alert is triggered.
Figure 3. IBM Cloud Monitoring notifications

For more information about configuring notifications, see Working with notification channels.
2. If you return to one of the dashboards that you created, you can click on the action menu in the upper right corner for any
panel, and then click Create Alert from the drop-down menu.
Figure 4. IBM Cloud Monitoring alerts
After you configure the alert based on your custom triggers, scroll down to associate the notification channel that you
configured above and select your notification preferences. Optionally, you can also enable IBM Cloud Monitoring capture
which generates a trace file that you can use to analyze what happens in a host during a selected time frame.
For more information about the various options when configuring alerts in IBM Cloud Monitoring. see IBM Cloud Monitoring
alerts.
Tip: As a general guideline, we recommend that you configure alerts for when your node CPU, memory, and storage
usage exceeds 80% so that you can take appropriate action. Feel free to adjust the alert settings according to your
notification preferences.
Summary
This tutorial has provided some basic steps for getting started using IBM Cloud Monitoring to monitor your blockchain node
resource allocation. You now have three dashboards that you can use to monitor the resource allocation of your peer, CA, and
ordering nodes in your Kubernetes cluster. With a graduated tier purchase of the IBM Cloud Monitoring service, you can edit your
charts and add more segmentations to further scope the data. You've also configured alerts for when nodes approach exceeding
their allocated resources. Combined, these actions allow you to monitor your blockchain nodes, alerting you when resources are
constrained, so that you can take the appropriate action to scale your network.
Prometheus metrics
As an alternative to IBM Cloud® Monitoring, you can use the Prometheus open-source systems monitoring and alerting toolkit to
monitor your IBM Blockchain Platform peer, orderer, and certificate authority (CA) nodes, and smart contract containers.
This tutorial helps you get started using Prometheus to monitor resource usage of peer, CA, and ordering service nodes. It
describes how to configure Prometheus to monitor your existing IBM Blockchain Platform service instance.
Monitoring node resource allocation is critical to operating a blockchain network. You are responsible for monitoring resource
usage and taking steps to address any resource contention. Prometheus is a useful tool for monitoring resources, but you can
use any comparable alternative.
Before you begin

Before using this tutorial, you should have an IBM Blockchain Platform service instance deployed and configured with peer, CA,
and ordering service nodes running and ready for monitoring. You will also use the IBM Blockchain Platform Console.
Step one: Create a Sysdig identity to access nodes

Sysdig uses mutual Transport Layer Security (TLS) to access cluster nodes. Use your organization’s TLS certificate authority (CA)
to generate a private and public key pair for your new Sysdig identity.
For the component you are scraping Prometheus metrics from, select the CA that issued its certificates. Then, click Register
User to create a new user identity that will access your network from Sysdig. Specify the Enroll ID and Secret for this user,

and set the type to client .
Next, click Enroll Identity and select the TLS Certificate Authority from the CA drop-down list. Enter the Enroll
ID and Secret that you specified in the previous step. When you click Next , the subsequent panel contains the certificates
generated for your new user identity.
Enter an Identity display name . Click Add identity to Wallet to store the keys in your console wallet. These
certificates are stored in the browser and are not saved by IBM Blockchain Platform. It is your responsibility to manage the
certificates and keep them secure—click Export identity to save the identity to your file system for importing back into the
wallet, as needed. Export the Certificate and Private key to the file system.
Note: If you have multiple components with certificates issued by the same CA, it is not necessary to create a new
identity for each component—the certificates generated for the identity will be valid for all of these components. To collect
metrics for components with certificates issued by a different CA, repeat the previous steps (create a new identity) for this
other CA.
Step two: Provision an IBM Cloud Monitoring instance

In this step you will provision an IBM Cloud Monitoring instance, which collects and displays metrics for Kubernetes clusters,
including IBM Blockchain Platform Prometheus metrics.
Navigate to the Catalog from your IBM Cloud dashboard and search for IBM Cloud Monitoring . Platform Metrics does
not have to be enabled for Prometheus metrics to work. Furthermore, you can choose any region to locate the instance—the
region will not affect the setup.
Once your IBM Cloud Monitoring instance is provisioned, navigate to Get Started > Install the agent > Add Sources .
This will redirect you to the command for installing sysdig agents on your Kubernetes cluster. Log in to your cluster using the
CLI and run the Public Endpoint curl command to install the agents, if necessary.
Step three: Configure the TLS secret

Configuring Sysdig created the ibm-observe namespace in your Kubernetes cluster. You will repeat this configuration for
Prometheus by editing the associated daemonset and configmap . First, store the downloaded TLS certs in a Kubernetes secret
by logging into the cluster (via the CLI) and running the following commands.
Create a TLS secret in the ibm-observe namespace by running the following command, where <cert-path> and <key-
path> are the paths to the certs you downloaded to your local file system. Be sure to keep a record of the <secret-name> that
you use:
$ kubectl create secret tls <secret-name> --cert=<cert-path> --key=<key-path> -n ibm-observe
Note: If you are setting up Prometheus metrics for components from multiple CAs, run the previous command for each
set of generated certificates, making sure to give them each a unique <secret-name> .
Next, get the current daemonset by running:
$ kubectl get daemonset sysdig-agent -o yaml > dm-sysdig-agent.yaml -n ibm-observe
Edit the daemonset by locating spec.template.spec.containers.volumeMounts and adding the following section:
$ - mountPath: /<directory-path>

name: <volume-name>
For example:
$ - mountPath: /ibp
name: ibp-volume
Note: If you set up multiple secrets, you should add as many volumeMounts as there are secrets, making sure to specify
a unique directory-path and volume-name for each one.
Next, edit the daemonset by locating spec.template.spec.containers.volumes and adding the following section:
$ - name: <volume-name>
secret:
defaultMode: 420
secretName: <secret-name>
For example:
$ - name: ibp-volume
secret:
defaultMode: 420
secretName: sysdig-tls-cert-key
Note: If you set up multiple volumeMounts , you should add as many volumes as there are volumeMounts , each using
the corresponding unique name and secretName .
Copy dm-sysdig-agent.yaml to dm-sysdig-agent-modified.yaml .
Finally, apply the modified daemonset by running:
$ kubectl apply -f dm-sysdig-agent-modified.yaml
Step four: Configure Prometheus settings

Configure the Prometheus scraper by modifying the configmap of the sysdig-agent .
First, get the current configmap by running:
$ kubectl get configmap sysdig-agent -o yaml > cm-sysdig-agent.yaml -n ibm-observe
Edit the configmap by adding the following lines as a sibling of the dragent.yaml section, replacing <directory-path> with
the path set up in the previous step:
$ prometheus.yaml: |
global:
scrape_interval: 10s
scrape_configs:
- job_name: 'ibm-blockchain'
scheme: https
tls_config:
insecure_skip_verify: true
cert_file: /<directory-path>/tls.crt
key_file: /<directory-path>/tls.key
metrics_path: /metrics
kubernetes_sd_configs:
- role: pod

relabel_configs:
- action: keep
source_labels: [__meta_kubernetes_pod_label_creator]
regex: ibp
For example:
$ prometheus.yaml: |
global:
scrape_interval: 10s
scrape_configs:
- job_name: 'ibm-blockchain'
scheme: https
tls_config:
insecure_skip_verify: true
cert_file: /ibp/tls.crt
key_file: /ibp/tls.key
metrics_path: /metrics
kubernetes_sd_configs:
- role: pod
relabel_configs:
- action: keep
source_labels: [__meta_kubernetes_pod_label_creator]
regex: ibp
Note: To scrape metrics for multiple components, add a new job by duplicating the job_name: 'ibm-blockchain'
section, specifying a unique job_name , and modifying the cert_file and key_file fields to the correct location.
Copy cm-sysdig-agent.yaml to cm-sysdig-agent-modified.yaml .
Finally, apply the modified configmap by running:
$ kubectl apply -f cm-sysdig-agent-modified.yaml
The sysdig-agent pods should automatically restart when the daemonset is applied, but you should still manually restart
them after applying the configmap , using either the CLI or the Kubernetes dashboard.
Step five: View Prometheus metrics

View Prometheus metrics by clicking the Explore tab in your IBM Cloud Monitoring dashboard. From Hosts & Containers ,
click Entire Infrastructure . Expand Overview by Host and scroll down to view the Prometheus metrics.
Figure 1. Explore metrics in IBM Cloud Monitoring
Dashboards are useful for saving customizations to a chart for later viewing. Simply create a new IBM Cloud Monitoring
dashboard and click + to add a new panel, where you can select the metric and segmentation type. The process for creating a
new dashboard is described in the IBM Cloud Monitoring documentation.

Backing up and restoring components and networks
Users might want to back up their components individually or the network generally for a number of reasons. While it's a best
practice to back up components before upgrading them to a new Fabric version, network backups can be useful for cases in
which a flawed smart contract causes invalid transactions to be written to the ledger. While a proper development and testing
cycle for a smart contract catches these errors, it might be necessary to reinstate a previous version of the network before the
invalid transactions were written.
Important: Taking snapshots as described in this topic does not protect against the deletion of a component or entire
environment by a user. This is because restoring a deleted component or environment requires more information than is
stored in a snapshot. Also, when a component or environment is deleted, the original volumes (which contain things like
certificates) and all snapshot data are deleted.
Overview
As with anything that is deployed to a Kubernetes-based cluster, backups of components and networks in the IBM® Blockchain
Platform are a matter of backing up its persistent volumes. These volumes are where ledgers and other types of storage are
mounted so they can be used by nodes.
As a result, "backing up" a component or a network is the process of saving a copy of the relevant persistent volumes, while
"restoring" a component or network involves bringing up components and pointing them to these saved volumes. The number of
volumes that are associated with a node depends on the type of node. Peers have either one persistent volume (if using
LevelDB) or two persistent volumes (if using CouchDB), while each node in the ordering service has a single persistent volume.
Important: Because an ordering node cannot pull blocks from a peer,all peers must be backed up before the ordering
nodes. This order ensures that the peers do not have any blocks on their ledgers that don't appear on the ledgers of the
backed-up ordering nodes. If any peers have blocks that the ordering nodes do not have, the ledgers cannot be
synchronized, making the restoration of the network impossible. If you are backing up your ledger as part of an upgrade to
a new Fabric version, you do not have to synchronize this backup with the rest of the network. However, make sure to
keep at least one ledger backup that is synchronized with the rest of the network in case a larger network restoration is
necessary.
If you're using CouchDB, which is mounted in a separate container in the peer pod, back up the persistent volume associated
with CouchDB before the volume associated with the peer pod. This is because the peer checks on CouchDB after booting and if
anything is missing from CouchDB, the peer can push transactions to it which CouchDB integrates into the database. However,
any transactions in the state database cannot be pushed back to the peer.
As a rule, it is a good practice to schedule backups (also known as "snapshots") to happen at the same time across the network.
For example, if all of the peers in the network are using CouchDB, schedule all of the CouchDB persistent volumes to be backed
up at the same time, followed by all of the peer persistent volumes (again, at the same time), and then the ordering node
persistent volumes (if multiple organizations are contributing ordering nodes, these snapshots must be coordinated with other
organizations). For an example of a backup schedule a network might choose to adopt, check out Scheduling snapshots.
While it is a best practice to periodically back up your Certificate Authority, these backups do not have to be coordinated with the
rest of the network. CAs with a local database have a single persistent volume. If you are using PostgreSQL , the CA has an
additional persistent volume associated with it that must also be backed up. For information about how to take backups of a
PostgreSQL database, check out Managing Backups from the Databases for PostgreSQL documentation.
The following node-specific guidance is provided to help plan your disaster recovery strategy.

Backup considerations for each node type
Consult the following chart to help you plan your strategy for taking backups:
Backup Restore
CAs must be stopped and backed up following the You can restore a CA without impacting the peers or the
instructions that are provided in this topic. ordering nodes ability to process transactions.
Table 1. Considerations for node backup and restore - CA
Backup Transaction Private data considerations

processing
Ideally, all peers in the network should be Unless the If the peers include private data collections, the
backed up daily at the same time. If the peers peers are peer and ordering nodes must be using Fabric
have a CouchDB state database, CouchDB must scaled down version v.2.2.1 or higher, otherwise every node
be backed up before the peer pod. Ordering to zero as part must be backed up at exactly the same ledger
nodes should be backed up after the peers. If of backing up height. This can be achieved by scaling down the
peers have data that the ordering service does private data, resources of the peers to zero as part of the
not, synchronization of components cannot transaction backup. For more information, see Scheduling
occur. processing snapshots.
can continue.
Table 2. Considerations for node back up and restore - Peer
Backup Transaction processing Restore
Ideally, all nodes in the ordering service Transaction processing If you are not using private data collections,
should be backed up daily at the same continues as normal you can provision new peers and rejoin the
time. The ordering service should be during a backup. If a channels. The peers can sync up with the
backed up after the peers to ensure that restoration is necessary, latest data from the ordering service, then you
the restoration of components can occur the ordering service must can reinstall any smart contracts.
later. be brought down. Or, you can restore the peers from a backup
older than the ordering nodes. In this case, the
peers only must catch up from the last backup,
which is faster. Any smart contracts installed
since the last backup must be reinstalled.
If you are using private data collections, the
peers must be restored to exactly the same
block height as the orderers. The best way to
ensure this is to back up all peers while the
ordering service is also down for the backup.
Table 3. Considerations for node back up and restore - Ordering service
Scheduling snapshots
It is a best practice to create a regular schedule for the snapshotting of your components. If possible, try to coordinate these
snapshots with the other members of your network to ensure that the most recent snapshots can be used if necessary. Because
no peer snapshots can be used that are more recent than ordering service snapshots, you are bound by your snapshots of the
ordering service when attempting to restore.
Tip: Even though snapshots do not disrupt the functionality of your nodes, try to schedule snapshots during a time when
the fewest transactions are being made. This ensures that differences in ledger heights between peers are kept to a
minimum. In widely distributed networks, scheduling such a time might be difficult. Prioritize the proper ordering of
snapshots over relative lulls in network activity.
For this example, we assume one backup every 24 hours and retain seven backups.
For the peer pods:

CouchDB snapshot daily at 3:00 a.m.
Peer snapshot daily at 3:05 a.m.
For the ordering node pods:
Ordering node snapshots daily at 5:00 a.m. The two-hour gap allows sufficient time for all of the peers to be snapshotted
from every organization before ordering nodes are snapshotted.
If you are using private data collections in your applications, your nodes must be running Hyperledger Fabric 2.2.1 or higher in
order to back up peer and ordering nodes while they are running. When restoring from a backup, the peers must be restored
from a lower block height than the ordering nodes. While peers can catch up to the block height of the ordering service, the
ordering service does not have the actual private data (in a private data transaction, only hashes of the data are committed to
the public ledger), rendering the data for these blocks unavailable. Fabric v2.2.1 and higher has a configurable option to lower
the priority for the reconciliation of missing private data. Earlier versions constantly attempt to reconcile the missing private
data, potentially blocking out reconciliation of other private data. On earlier versions of Hyperledger Fabric, you must back up
ordering nodes and peers at exactly the same block heights to avoid this issue. This can be accomplished by scaling the both the
peer and ordering node pods to 0 before taking the backup.
Taking snapshots
The overall steps for the backup and restore process apply in all cases and are independent of where your components are
deployed. However, the specific commands that are used in this example for creating, listing, and restoring snapshots apply only
if you are running on IBM Cloud. For other cloud providers or when running in your own datacenter, follow the specific
instructions for underlying snapshot creation and management found in the documentation of those providers.
Tip: When a snapshot is being taken the node continues to function as normal.
Node snapshots
Tip: Because the process for taking a snapshot is the same for all nodes, only one set of instructions is shown here.
After your node is provisioned, you can get the persistent volumes that are associated with it and the namespace the component
is deployed into by issuing:
kubectl get pvc --all-namespaces
Which produces a list of nodes and their persistent volumes similar to this example:
NA.M.ESPACE NA.M.E STATUS VOLUME CAPACITY

ACCESS MODES STORAGECLASS AGE
n3392fd orderer1node1-pvc Bound pvc-34723fe1-c8e9-4fe7-bdf8-75b8a2f22912 100Gi RWO
ibmc-file-bronze 49d
n3392fd orderer2node1-pvc Bound pvc-11b34473-bfdf-4fac-962b-5999bb961a50 100Gi RWO
n3392fd orderer3node1-pvc Bound pvc-33ed8cce-21ec-44a8-8a0f-190052b985f9 100Gi RWO
n3392fd orderer4node1-pvc Bound pvc-5fd2b807-2361-406b-802a-a18dbaabe23e 100Gi RWO
n3392fd orderer5node1-pvc Bound pvc-01da603e-3d2b-4b77-a0ac-af3e70e2d2f5 100Gi RWO
n3392fd ordererorgca-pvc Bound pvc-e582ef7f-04ae-4493-9bdb-426c784886c3 20Gi RWO
n3392fd peera-pvc Bound pvc-def5a60c-25f3-4de0-b9cc-2cf8dcf88cc2 100Gi RWO
n3392fd peera-statedb-pvc Bound pvc-494ba122-3501-4413-b719-cbb4b3a8f91b 100Gi RWO

n3392fd peerc-pvc Bound pvc-ba9cee42-4d35-48d9-ad05-85afc7256633 100Gi RWO
n3392fd peerc-statedb-pvc Bound pvc-e945df85-5a32-4d37-991d-b2be334bc09b 100Gi RWO
n3392fd peerorg1ca-pvc Bound pvc-152be78e-202d-43a4-bcf7-81a6a9013c2d 20Gi RWO
To get the details on a particular volume, issue:
kubectl describe pv <VOLUME>
If you are using the CLI to manage snapshots, you'll need the volumeId value. If you are using the cluster UI, you'll need the
Username value. For an example volume named pvc-494ba122-3501-4413-b719-cbb4b3a8f91b , you would issue this
command:
kubectl describe pv pvc-494ba122-3501-4413-b719-cbb4b3a8f91b
Which produces a list of details similar to this example:
Name: pvc-494ba122-3501-4413-b719-cbb4b3a8f91b
Labels: CapacityGb=100
Datacenter=dal10
Iops=2
StorageType=ENDURANCE
Username=IBM02SEV2046428_106
billingType=hourly
failure-domain.beta.kubernetes.io/region=us-south
failure-domain.beta.kubernetes.io/zone=dal10
path=IBM02SEV2046428_106data01
server=fsf-dal1002h-fz.adn.networklayer.com
volumeId=155617812
Annotations: ibmFileProvisionerIdentity: 44cc1a5f-b755-11ea-bfae-3692beefed97
pv.kubernetes.io/provisioned-by: ibm.io/ibmc-file
Finalizers: [kubernetes.io/pv-protection]
StorageClass: ibmc-file-bronze
Status: Bound
Claim: n3392fd/peera-statedb-pvc
Reclaim Policy: Delete
Access Modes: RWO
VolumeMode: Filesystem
Capacity: 100Gi
Node Affinity: <none>
Message:
Source:
Type: NFS (an NFS mount that lasts the lifetime of a pod)
Server: fsf-dal1002h-fz.adn.networklayer.com
Path: /IBM02SEV2046428_106/data01
ReadOnly: false
Events: <none>
You can then order snapshots for that volume, which can be done by using either the CLI or the cluster UI. For information on
how to take the snapshot, see Ordering Snapshots.
Tip: In this case, "ordering" refers to the "order to take snapshots" and not "ordering nodes".
For our example, we use the CLI and order a single snapshot by using 5 GB of space by issuing:
ibmcloud sl file snapshot-order 155617812 -s 5
Tip: You might need more or less than 5 GB of space, depending on the size of the pod and the resources that have been

used on it. The amount of space that is required depends on the size of your transactions, the quantity of transactions,
and how many snapshots (or backups) that you want to keep. To determine how much storage you are using, monitor the
disk space that is consumed by your nodes so that you know when to add storage. You can use this data to inform how
much storage is being used, and how fast it is growing. Also, if you monitor the size of each snapshot, you can use the
snapshot size along with the number of snapshots you want to keep to determine when more snapshot space is required.
Taking a snapshot incurs charges on your account. Press y to accept the charges and order the snapshot.
Alternatively, you can enable snapshots to be taken on a regular schedule for a particular volume. For information on how to set
of a snapshot schedule, see Adding a Snapshot schedule.
Again, for our example, we use the CLI to set up a daily snapshot of a CouchDB volume at 3:00 a.m. and retain seven snapshots.
ibmcloud sl file snapshot-enable 155617812 -s DAILY -c 7 -r 3
Which produces a message similar to the following:
OK
DAILY snapshots have been enabled for volume 155617812.
We can now list the snapshot schedule to verify it's in place by issuing:
ibmcloud sl file snapshot-schedule-list 155617812
Which produces a message similar to the following:
id active type replication date_created minute hour day week

day_of_week date_of_month month_of_year maximum_snapshots
542130 * DAILY - 2020-09-02T16:35:58Z 0 3 * - *
* * 7
Repeat the following steps for each pod you want to back up, remembering to schedule your backups in the proper order.
Restoring nodes
Tip: If you have to restore a node, first cancel any scheduled snapshots. Only restore from a snapshot that does not have
bad or corrupted data. After a node has been restored, you can reimplement your snapshot schedule.
Here we have two examples. In the first example, we show the steps for restoring peer nodes, while in the second example, we
describe the steps for restoring the ordering service, which requires restoring peer nodes as well.
Because the details for finding the persistent volumes that are associated with each ordering node and restoring snapshots are
identical to what is documented for the peer, the commands are only listed once, in the peer instructions. However, additional
considerations when restoring ordering nodes are documented in Restoring an ordering node.
Sequencing restorations
Just as when backing up, care must be taken to restore things in the proper order. When restoring ordering nodes, for example,
even if you only restore one node, scale down all of the pods of the ordering nodes by reducing their resources to zero. If every
ordering node must be restored, the best practice is to stop them all at once and then restore them all at once. Then, make sure
all of them come up and give them a few minutes to elect a leader and establish quorum before driving any transactions.
If you are restoring the ordering service from a backup, you must also either create new peers or restore all peers to a backup

older than the ordering service. Peers restored from an older backup can catch up to the latest data by receiving blocks from the
ordering service.
When restoring a peer, make sure to restore backups of CouchDB older than the backup of the peer pod. If your state database
has transactions your peer does not have, the database cannot sync with the peer.
Restoring a peer
To restore a peer, you need to:
1. Find the deployment that you want to restore.

2. Scale it down to zero to stop the node.
3. Restore the node from the backup.
First, get the list of deployments:
kubectl get deployments
As before, this produces a list of nodes and their persistent volumes similar to this example:
NA.M.E READY UP-TO-DATE AVAILABLE AGE

ibp-operator 1/1 1 1 48d
orderer1node1 1/1 1 1 20h
ordererorgca 1/1 1 1 48d
peera 1/1 1 1 20h
peerc 1/1 1 1 20h
peerorg1ca 1/1 1 1 48d
Then scale down the node by setting the replicas value to 0 .
kubectl patch <component> <componentName> --type merge --patch '{"spec":{"replicas":0}}' -n

<namespace>
Where <component> is one of: ibppeer , ibporderer , or ibpca .
In this example, scale down peera :
kubectl patch <ibppeer> peera --type merge --patch '{"spec":{"replicas":0}}' -n n3392fd
Then look at your deployments again to make sure that the peer is scaled down:
You'll receive a response similar to:

peera 0/0 0 0 20h
peerc 1/1 1 1 20h

Note that peera is not ready.
Use the commands in the Peer snapshot section to find the persistent volumes that are associated with the peer. Peers using
CouchDB have two volumes.
For each volume, list the available snapshots for that volume. For information on how to list available snapshots, see Listing all
Snapshots with Space Used Information and Management functions.
For our example, we use CLI and restore a specific snapshot from our volume ID for the CouchDB pod that is associated with
peera :
ibmcloud sl file snapshot-list 155617812
Which shows the available snapshots:
id user_name created size_bytes notes

167189176 IBM02SEV2046428_106 2020-09-03T03:00:00-05:00 143089
Pick the snapshot you'd like to restore from the list, keeping in mind that the CouchDB backup must be older than the peer pod
backup, and restore it. For information on how to restore the snapshot, see Restoring storage volume to a specific point-in-time
by using a snapshot.
Restore by using the snapshot:
ibmcloud sl file snapshot-restore <volumeid> <snapshotid>
There is only one snapshot available here, so select it:
ibmcloud sl file snapshot-restore 155617812 167189176
A successful snapshot restoration looks similar to:
OK
File volume 155617812 is being restored using snapshot 167189176.
Important: Restoring a volume results in deleting all snapshots that were taken after the snapshot that was used for the
restore.
Repeat the process for the other volume used by the peer container, which can be found by using the same commands. Choose
the 3:05 a.m. snapshot corresponding to the 3:00 a.m. snapshot you restored for CouchDB volume.
Once both snapshots are restored, scale the deployment back up to one to redeploy the pod with the new data. First, check the
status of the pods:
You'll receive a response similar to:


peera 0/0 0 0 20h
peerc 1/1 1 1 20h
Then scale the peera pod back up by setting the replicas value to 1 .
kubectl patch <component> <componentName> --type merge --patch '{"spec":{"replicas":1}}' -n

<namespace>
Where <component> is, once again, one of: ibppeer , ibporderer , or ibpca .
In this example, scale up peera :
kubectl patch <ibppeer> peera --type merge --patch '{"spec":{"replicas":1}}' -n n3392fd
Once the pod is back up, the peer is now restored, with the same peer channel membership, installed smart contracts, and
ledger height as when the snapshot was taken. Because the peer immediately starts pulling new blocks from the ordering
service or other peers once it comes up, the ledger height might increase.
Restoring an ordering node

The process for restoring an ordering node is largely similar to the process for restoring a peer. However, there are a few
additional things to keep in mind.
1. You must stop all the ordering nodes in the cluster by scaling down each deployment to zero before restoringany of the
ordering nodes. Note after the nodes have been scaled down, it is not possible to transact. Client applications must
resubmit their transaction requests after the ordering service is restored.
2. If you restore all ordering nodes, you must scale all the deployments up to1 to restart them and give them five minutes to
determine leadership before accepting any traffic. It is a best practice to also stop all peers on the network during this
process.
3. You must then restore all peers that are connected to that ordering service to a backup taken earlier than the ordering
service backup you are restoring to, or provision new peers.
In our example, the flow you would take is:
1. Scale down all five ordering nodes and peer deployments to zero to stop all traffic on the network.
2. Restore the peer nodes to the 3:00 a.m. CouchDB snapshot and the 3:05 a.m. peer pod snapshot.
3. Restore each ordering node to its 5:00 a.m. snapshot taken the same day as the peer snapshots you restored.
4. Scale all five ordering service deployments up to 1 and wait for five minutes after they have started to sync up.
5. Scale all peer deployments up to 1.

Building a network with APIs
The IBM® Blockchain Platform exposes RESTful APIs for you to create, import, edit, and delete your blockchain components, as
well as to manage logging, notifications, and console settings. You can use the APIs, and the corresponding SDKs, to develop
applications that interact with your blockchain network.
This tutorial introduces the generic flow to build a blockchain network with IBM Blockchain Platform APIs. For more information
about each API, see IBM Blockchain Platform API reference doc.
Swagger
After you review the instructions in this topic on how to use the APIs, you can alternatively access a Swagger version of the APIs
instead of the APIs in IBM Cloud where the current version is v2 . If you need to access the v1 version of the APIs, you can
import the v1 version into the Swagger editor.
v1
v2
Before you begin

You must have an IBM Blockchain Platform service instance in IBM Cloud so that you can issue API calls to interact with the
network. If you do not have a service instance yet, follow the Getting started instructions to create one.
Authentication
In order to use the APIs to access your blockchain network that you create with IBM Blockchain Platform, your application needs
to be able to authenticate with IBM Cloud and connect to your service instance.
Retrieving service credentials

You need a basic authentication credential to ensure that you have access to your IBM Blockchain Platform service instance on
IBM Cloud.
1. In your IBM Cloud resource list, under Services, open the blockchain service instance that you created.
2. Click Service credentials from the left navigator.
3. Click the New Credential button on the Service credentials page to create a new credential.
1. Give the credential a name, for example, UseAPIs.
2. You can leave the Add inline configuration parameter field blank.
3. Click the Add button.
4. After the new credential is created, click View credentials under the ACTIONS header of this credential. The contents of
the credential looks similar to the following example:
{
"api_endpoint": "https://1088ac8563e44f5a92539d946733ad7e-
optools.so01.blockchain.test.cloud.ibm.com"
"apikey": "nvASKts6B6lMZGZUNTGVP7MLK2BujMnxz0plSPYaqc3R",
"configtxlator": "https://1088ac8563e44f5a92539d946733ad7e-
configtxlator.so01.blockchain.test.cloud.ibm.com",
"iam_apikey_description": "Auto generated apikey during resource-key operation for Instance
- crn:v1:staging:public:blockchain:us-south:a/9d46037caee397faa45c55e087d26baa:1088ac85-63e4-
4f5a-9253-9d946733ad7e::",
"iam_apikey_name": "auto-generated-apikey-c1981f5c-cff0-464f-9a78-ed2f52e24d1a",
"iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
"iam_serviceid_crn": "crn:v1:staging:public:iam-
identity::a/9d46037caee397faa45c55e087d26baa::serviceid:ServiceId-774190c5-9c37-4f68-8572-
8d6e2aabbc7e",
}

In the service credential, you can find the API key ( apikey ) and API endpoint ( api_endpoint ) that you need to retrieve a
Cloud Identity and Access Management (IAM) access token.
Retrieving an access token

You can authenticate with IBM Blockchain Platform by retrieving an access token from IAM. With an access token, you can work
with the IBM Blockchain Platform API on behalf of your service or application on or outside IBM Cloud, without needing to share
your personal user credentials.
Call the Cloud Identity and Access Management API to retrieve your access token.
curl -X POST \
"https://iam.cloud.ibm.com/identity/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>" \
In the request, replace <API_KEY> with the apikey value from your service credentials. The following truncated example
shows the token output:
{
"access_token": "eyJraWQiOiIyM...",
"refresh_token": "...",
"expires_in":3600,
"expiration":1555558683,
"scope":"ibm openid"}
Use the full access_token value, prefixed by the Bearer token type, to programmatically work with your blockchain network
by using the APIs.
Tip: Access tokens are valid for one hour, but you can regenerate them as needed. To maintain access to the service,
refresh the access token for your API key on a regular basis by calling the Cloud Identity and Access Management API.
Forming your API request

When you make an API call to the service, structure your API request according to how you initially provisioned your IBM
Blockchain Platform service instance.
To build your request, pair an API endpoint with the appropriate authentication credentials in the following format:
curl -X <API method> \

<API_endpoint>/<API> \
-H 'authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '<request body>' \
Example cURL commands are provided for each API in the IBM Blockchain Platform API reference doc.
Limitations
You can only import CA, peer, and ordering nodes that are exported from other IBM Blockchain Platform consoles running on
IBM Cloud, OpenShift Container Platform, Red Hat Open Kubernetes Distribution, or any Kubernetes v1.23 - v1.24 container
platform on x86_64. The platform is also supported on LinuxONE (s390x) using OpenShift Container Platform.
Building a network by using APIs

You can use APIs to create blockchain components in your instance of the IBM Blockchain Platform. Use the following steps to
build a blockchain network by using the IBM Blockchain APIs.
1. Create a Certificate Authority (CA) by calling POST /ak/api/v2/kubernetes/components/ca.
Tip: Remember your input and the response, you will need them later.
You need to wait for the CA to start. It might take several minutes depending on environment. You can call GET
<ca_url>/cainfo API to check your CA status. You will get repeated errors, then a 200 status code, which means you
can proceed to the next step. Note that this API call times out after one minute.
2. Use your CA to register your component and administrator identities, and generate the necessary certificates. You can use
the Fabric CA client to complete the following steps:
Set up the Fabric CA client.

Generate certificates with your CA admin.
Register the new component with your CA.
You also need to register an organization administrator and then generate certificates for the admin inside an MSP
folder. You do not have to complete this step if you have already registered your admin identity.
Register the new component with your TLS CA.
You can also complete these steps by using your IBM Blockchain Platform console. For more information, see
Creating and managing identities.
3. Create an MSP definition for your organization by calling POST /ak/api/v2/components/msp.
4. Build the configuration file that is required to create an ordering service or peer. You must build a unique configuration file
for each ordering service or peer that you want to create. If you are deploying multiple ordering nodes, you need to provide
a configuration file for each node that you want to create.
5. Create an ordering service by calling POST /ak/api/v2/kubernetes/components/orderer.
6. Create a peer by calling POST /ak/api/v2/kubernetes/components/peer.
7. If you want to use the console to operate your blockchain components, you must import your administrator identity into
your console wallet. Use the wallet tab to import the certificate and private key of your node admin into the console and
create an identity. You then need to use the console to associate this identity with the components you created. For more
information, see Importing an admin identity into the IBM Blockchain Platform console.
8. After you deploy your network, you can use the Fabric SDKs, the Peer CLI, or the console UI to create channels and deploy
smart contracts. If you need to programmatically create a channel, you must provide the consortium name. For IBM®
Blockchain Platform, the consortium name must be set to SampleConsortium .
Note: The service credential that is used for API authentication must have the Manager role in IAM to be able to create
components. See the table on user roles for more information.
Creating a node within a specific zone

If you are using a multizone cluster, you can use the APIs to deploy a blockchain component to a specific zone of IBM Cloud.
This allows your network to maintain availability in the event of a zone failure. You can use the following steps to deploy a peer
or ordering node to a specific zone.

1. Find the zones that your worker nodes are located. Navigate to the Kubernetes service or OpenShift cluster overview
screen of your multizone cluster on IBM Cloud. From the cluster overview screen, select your cluster and click Worker
Nodes to see a table of all the worker nodes in your cluster. You can find the zone where each worker node is located in
the Zone column of the table.
You can also find the zones of your worker nodes by using the kubectl CLI. Navigate to the Access panel and follow the
instructions under Gain access to your cluster to connect to your cluster by using the IBM Cloud and kubectl CLI tools.
When you are connected, use the command kubectl get nodes --show-labels to get the full list of nodes and zones
of your cluster. You will be to find the zone that each worker node is located after zone field under the LABELS column.
1. To create a node within a specific zone, provide the zone name to the Create an ordering service or Create a peer API
calls by using the zone field of the request body. The anti-affinity policy of the IBM Blockchain Platform console will
automatically deploy your component to different worker nodes within each zone based on the resources available.
Creating a node with a custom configuration

If you are using the IBM Blockchain APIs to deploy a CA, peer, or ordering node, you have the option of customizing the node
configuration by using a configuration override JSON string. The nodes that are deployed by the IBM Blockchain Console and
APIs are configured with the default Fabric values that are provided in the fabric-ca-server-config.yaml , orderer.yaml ,
and core.yaml files. You can customize your node settings by providing a configuration override JSON to the APIs that create
or update your nodes. You can use the configuration override to deploy a High Availability CA or use a Hardware Security Module
(HSM) while using the IBM Blockchain APIs. For more information about the configuration override, High Availability CAs, or
HSMs, see Advanced deployment options.
Example: Creating a custom Certificate Authority

If you are using the Create a CA API to deploy a Certificate Authority, you need to use the configuration override JSON string to
set the CA admin enrollID and secret. For example, if you wanted to create a CA with an administrator enrollID and secret of
admin and adminpw , you would issue the following command. You can use the command to create multiple admins. The API
would create a CA that uses the default values for all other fields.
curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-ca" \

-H "Content-Type: application/json" \
-H "Authorization: Bearer {IAM-Token}" \
-d "{
\"display_name\": \"My CA\",
\"config_override\":{
\"ca\":{
\"registry\":{
\"maxenrollments\": -1,
\"identities\": [{
\"name\": \"admin\",
\"pass\": \"password\",
\"type\": \"client\",
\"affiliation\": \"\",
\"attrs\":{
\"hf.Registrar.Roles\": \"*\",
\"hf.Registrar.DelegateRoles\": \"*\",
\"hf.Revoker\": true,
\"hf.IntermediateCA\": true,
\"hf.GenCRL\": true,
\"hf.Registrar.Attributes\": \"*\",
\"hf.AffiliationMgr\": true
}
}]
}
}
}
}"

You use also the "configoverride" to create or update a CA with custom settings for your organization. This provides you with
more control over the identities and certificates that are created by your CA. For example, you would use the following command
to set your organization name and location.
curl -X POST \
https://<API endpoint>/ak/api/v2/kubernetes/components/fabric-ca \
-H 'Authorization: Bearer <IAM_token>' \
-d "{
"display_name": "Sample CA",
"configoverride": {
"ca": {
"registry": {
"identities": [
{
"name": "admin",
"pass": "adminpw",
"type": "admin",
"affiliation": "",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}
}
},
"csr": {
"names": [
{
"C": "US",
"ST": "New York",
"L": null,
"O": "Big business",
"OU": "Big department"
}
],
}
}
}"
For more information about deploying a customized CA, and which fields you can customize after a CA is created, see
Customizing a CA configuration.
Create a high availability CA

You can use configuration override to deploy a CA with replica sets that share the same database, ensuring that the data is
consistent between replicas. This configuration ensures that the CA will be available in the event of a Kubernetes worker node
failure. To deploy an HA CA, you need to deploy a PostgreSQL database on IBM Cloud or in the environment of your choice. You
then need to use the information about your database to create a connection file that will be used by your CA. For more
information, see Building a high availability Certificate Authority.
To use the APIs to deploy an HA CA, you need to provide the database connection file to the "db" section of the config override
JSON string. For example, the API request below will deploy a CA with two replicas that connect to a database located on IBM
Cloud.
curl -X POST \

https://<API endpoint>/ak/api/v2/kubernetes/components/fabric-ca \
-H 'Authorization: Bearer <IAM_token>' \
-d '{
"display_name": "Sample CA",
"replicas": 2,
"configoverride": {
"ca": {
"db": {
"datasource": "host=test.databases.appdomain.cloud port=31941 user=ibm_cloud
password=password dbname=ibmclouddb sslmode=verify-full",
"tls": {
"certfiles": [
"<base64 encoded pem>"
],
"enabled": true
},
"type": "postgres"
}
},
"tlsca": {
"db": {
"datasource": "host=test.databases.appdomain.cloud port=31941 user=ibm_cloud
password=password dbname=ibmclouddb sslmode=verify-full",
"tls": {
"certfiles": [
"<base64 encoded pem>"
],
"enabled": true
},
"type": "postgres"
}
"registry": {
"identities": [
{
"name": "admin",
"pass": "adminpw",
"type": "admin",
"affiliation": "",
"attrs": {
"hf.Revoker": true,
"hf.GenCRL": true,
}
}
}
}
}
}'
Deploy a node that uses an HSM

IBM Blockchain Platform allows you to deploy CA, peer, or orderer nodes that use an HSM to store their private key. To use an
HSM with your blockchain network, you need to first set up an HSM on IBM Cloud or in your own environment. You then need to
set up a PKCS #11 proxy that allows your nodes to communicate with your HSM. You can then create a node with the private key
that is stored in an HSM partition by providing the HSM endpoint along with the slot key and pin before the node is deployed. For
more information, see Configuring a node to use an HSM.
If you are using the APIs to deploy a node, you need to provide the HSM endpoint to the HSM field of the API call. You also need
to use the config override to provide the label and pin of the HSM slot that you will use and select "PKCS11" as the default

crypto service provider. As an example The following API call deploys a peer node with an HSM.
curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-peer" \

-H "Content-Type: application/json" \
-H "Authorization: Bearer {IAM-Token}" \
-d "{
\"display_name\": \"My Peer\",
\"msp_id\": \"org2\",
\"config\": {
\"enrollment\": {
\"component\": {
\"cahost\": \"n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud\",
\"caport\": \"7054\",
\"caname\": \"ca\",
\"catls\": {
\"cacert\":
\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1
FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
},
\"enrollid\": \"admin\",
\"enrollsecret\": \"password\",
\"admincerts\": [
\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWw
KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"
]
},
\"tls\": {
\"cahost\": \"n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud\",
\"caport\": \"7054\",
\"caname\": \"tlsca\",
\"catls\": {
\"cacert\":
\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1
FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
},
\"enrollid\": \"admin\",
\"enrollsecret\": \"password\",
\"admincerts\": [
\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWw
KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"
]
}
}
},
\"hsm\": {
\"pkcs11endpoint\": \"tcp://example.com:666\",
},
\"config_override\": {
\"bccsp\": {
\"default\": \"PKCS11\",
\"pkcs11\": {
\"label\": \"blockchain\",
"pin": \"91927001\"
}
}
}
}"
Import a network by using APIs

You can also use the APIs to import IBM Blockchain components that are created by using the APIs or the IBM Blockchain
Platform console into another service instance of the IBM Blockchain Platform.
1. Import a CA by calling POST /ak/api/v2/components/ca.

Tip: Remember your input and the response, you will need them later.
You need to wait for the CA to start. It might take several minutes depending on environment. You can call GET
/components to check the CA status. You will get repeated errors before you get a 200 status code to go to next step.
Note that this API call times out in one minute.
2. Import an organization MSP definition by calling POST /ak/api/v2/components/msp.
3. Import an ordering service by calling POST /ak/api/v2/components/orderer.
4. Import a peer by calling POST /ak/api/v2/components/peer.
5. If you plan to use the IBM Blockchain Platform console to operate your blockchain components, you must import your
component administrator identities into your console wallet. For more information, see Importing an admin identity into
the IBM Blockchain Platform console.
6. After you deploy your network, you can use the Fabric SDKs, the Peer CLI, or the console UI to create channels and deploy
smart contracts. If you need to programmatically create a channel, you must provide the consortium name. For IBM®
Blockchain Platform, the consortium name must be set to SampleConsortium .
Note: The service credential that is used for API authentication must have the Manager role in IAM to be able to create
components. See the table on user roles for more information.
Operating your CA with the Fabric CA client

You can use the Fabric CA client to operate your CAs. Run the following Fabric CA client commands to register your component
and administrator identities and generate the necessary certificates.
Set up the Fabric CA client

1. Download the Fabric CA client to your local file system.
The easiest way to get the Fabric CA client is to download all of the Fabric tool binaries directly. Navigate to a directory
where you would like to download the binaries with your command line, and fetch them by running the following cURL
command.
curl -sSL http://bit.ly/2ysbOFE | bash -s 1.4.3 1.4.3 -d -s
This command installs the binaries in a bin/ directory.
2. Set the PATH path to the directory where you downloaded the Fabric tool binaries:
export PATH=$PATH:<full/path/to/fabric-ca-client/bin>
For example, if you installed the binaries in your home directory you would set your PATH as:
export PATH=$PATH:$HOME/bin
3. Create the folder where you will store the certificates of your CA admin.
mkdir -p $HOME/fabric-ca-client/ca-admin
4. Set the value of the $FABRIC_CA_CLIENT_HOME environment variable to be the path where the CA client will store the

generated MSP certificates. Ensure that you remove the configuration material that might be created by earlier attempts.
If you didn't run the enroll command before, the msp folder and the .yaml file do not exist.
export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca-client/ca-admin
rm -rf $FABRIC_CA_CLIENT_HOME/fabric-ca-client-config.yaml
rm -rf $FABRIC_CA_CLIENT_HOME/msp
5. Retrieve the TLS certificate of your CA to be used by the Fabric CA client. If you are using the IBM Blockchain Platform
console, open the CA and click Settings, and look for the certificate in base64 format in the TLS Certificate field. If your
are using the APIs, you can call GET /ak/api/v2/components and find the CA TLS certificate in the "PEM" field. If you
created the CA by using the Create a Fabric CA API, you can also find the TLS certificate in the response body.
You need to convert the certificate from base64 into PEM format to use it to communicate with your CA. Insert the base64
encoded string of the TLS certificate into command below. Ensure that you are in your $HOME/fabric-ca-client
directory.
cd $HOME/fabric-ca-client
mkdir catls
echo <base64_string> | base64 --decode $FLAG > tls.pem
Generate certificates with your CA admin

A CA admin identity was automatically registered for you when you created your CA. You can now use that admin name and
password to issue an enroll command with the Fabric CA client to generate an MSP folder with certificates that can then be
used to register other peer or ordering node identities.
1. Ensure that you complete the steps to set up the Fabric CA client and that $FABRIC_CA_CLIENT_HOME is set to the
directory where you want to store your CA admin certs.
echo $FABRIC_CA_CLIENT_HOME
$HOME/fabric-ca-client/ca-admin
2. Run the following command to generate certificates:
fabric-ca-client enroll -u https://<enroll_id>:<enroll_password>@<ca_url_with_port> --caname

<ca_name> --tls.certfiles <ca_tls_cert_path>
The <enroll_id> and <enroll_password> in the command are the enroll_id and enroll_secret you specified when
you created the CA. Use the Certificate Authority Endpoint URL from your IBM Blockchain Platform console or the
"ca_url" returned by your API call as the value for <ca_url_with_port> . Leave off the http:// at the beginning. The
<ca_name> is the CA Name from your console, or the "ca_name" returned by the APIs.
The <ca_tls_cert_path> is the full path your CA TLS cert.
A real call might look similar to the following example command:
fabric-ca-client enroll -u https://admin:adminpw@9.30.94.174:30167 --caname ca --tls.certfiles

$HOME/fabric-ca-client/catls/tls.pem
Tip: If the value of the enrollment URL, which is the -u parameter value, contains a special character, you need to either
encode the special character or surround the URL with the single quotation marks. For example, ! becomes %21 , or the
command looks like:
$ ```
./fabric-ca-client enroll -u 'https://admin:C25A06287!0@ash-zbc07c.4.secure.blockchain.ibm.com:21241'

--tls.certfiles $HOME/fabric-ca-remote/cert.pem --caname ca
```
The `enroll` command generates a complete set of certificates, which is known as a Membership Service
Provider (MSP) folder, that is located inside the directory where you set to `$HOME` path for your
Fabric CA client. For example, `$HOME/fabric-ca-client/ca-admin`. For more information about MSPs and
what the MSP folder contains, see the [Membership Service Providers](https://hyperledger-
fabric.readthedocs.io/en/release-2.2/msp.html){: external} concept topic in the Fabric documentation.
If the `enroll` command fails, see the [Troubleshooting topic](#ibp-v2-apis-config-troubleshooting)

for possible causes.
You can run a tree command to verify that you have completed all of the prerequisite steps. Navigate
to the directory where you stored your certificates. A tree command should generate a result similar
to the following structure:
```
tree
.
├── ca-admin
│ ├── fabric-ca-client-config.yaml
│ └── msp
│ ├── cacerts
│ │ └── 9-30-250-70-30395-SampleOrgCA.pem
│ ├── IssuerPublicKey
│ ├── IssuerRevocationPublicKey
│ ├── keystore
│ │ └── 2a97952445b38a6e0a14db134645981b74a3f93992d9ddac54cb4b4e19cdf525_sk
│ ├── signcerts
│ │ └── cert.pem
│ └── user
└── catls
└── tls.pem
```
Registering the component identity with the CA

First, you need to register a component identity with your CA. Your component uses this identity to generate the certificates it
needs when it is deployed.
1. Generate certificates with your CA admin by using the Fabric CA client. Use these admin certificates to issue the following
commands. Ensure that $FABRIC_CA_CLIENT_HOME is set to $HOME/fabric-ca-client/ca-admin .
2. Issue the following command to find your affiliation and your organization name.
fabric-ca-client affiliation list --caname <ca_name> --tls.certfiles <ca_tls_cert_path>
Your command might look like the following example:
fabric-ca-client affiliation list --caname ca --tls.certfiles $HOME/fabric-ca-

client/catls/tls.pem
You should see information that is similar to the following example:
affiliation: org1
affiliation: org1.department1
Make a note of the second affiliation value, for example, org1.department1 . You need to use this value in the command

below.
If you created the CA with the IBM Blockchain APIs instead of the console, your CA is deployed without affiliations, unless
you created affiliations by using the Fabric CA Client. If your CA does not have affiliations, you can skip this step and leave
the --id.affiliation off future commands.
3. Run the following command to register the ordering node or peer.
fabric-ca-client register --caname <ca_name> --id.name <name> --id.affiliation org1.department1 -

-id.type <component_type> --id.secret <secret> --tls.certfiles <ca_tls_cert_path>
Create a name and password for the component and then use them to replace name and secret . Make a note of this
information. Set the --id.type to orderer if you are deploying an ordering node, or set it to peer if you are deploying a
peer. The command might look similar to the following example:
fabric-ca-client register --caname ca --id.affiliation org1.department1 --id.name peer1 --

id.secret peer1pw --id.type peer --tls.certfiles $HOME/fabric-ca-client/catls/tls.pem
Important: You need to save the "enrollid" and "enrollsecret" from the command above for when you create
your configuration file.
You can register an identity only once. If you experience a problem, try a command with a new username and password. As
a security measure, use each identity, and the accompanying enrollID and secret, to deploy only one peer. While you can
use one admin identity for several components (this is the recommended deployment strategy), do not reuse peer IDs and
passwords.
When the command completes successfully, you should see information that is similar to the following example:
2018/06/18 16:53:00 [INFO] Configuration file location: /fabric-ca-platform/admin/fabric-ca-

client-config.yaml
2018/06/18 16:53:00 [INFO] TLS Enabled
2018/06/18 16:53:00 [INFO] TLS Enabled
Password: peerpw
Registering your organization administrator

You also need to create an admin identity that you can use to operate your network. You use this identity to operate specific
components, such as by installing a smart contract on your peer. You can also use this identity as an administrator of your
organization and use it to create and edit channels.
You need to register this new identity with your CA, and use it to generate an MSP folder. You can make this identity an
organization administrator by adding its signCert to your organization MSP. You also need to add the signCert to your
configuration file so that it can be made the admin cert of the ordering node or peer during deployment. You need to create only
one admin identity for your organization. As a result, you need to complete these steps only once. You can use the signCert that
you generated to deploy many peers or ordering nodes.
Ensure that your $FABRIC_CA_CLIENT_HOME is set to the path to the MSP of your CA Admin.
Register the component admin identity with the CA by running the following command:
fabric-ca-client register --caname <ca_name> --id.name <name> --id.affiliation org1.department1 --

id.type admin --id.secret <password> --tls.certfiles <ca_tls_cert_path>

Create a new user identity name and secret for the admin. Make sure to use different values than for the peer or ordering node
identity that you registered. The command looks similar to the following example:
fabric-ca-client register --caname ca --id.name peeradmin --id.affiliation org1.department1 --id.type

admin --id.secret peeradminpw --tls.certfiles $HOME/fabric-ca-client/catls/tls.pem
Important: Make a note of this information. You will use this name and secret to generate the MSP folder by using the
enroll command.
Generating the admin Membership Service Provider (MSP) folder

After your register the component admin, you can generate certificates by running the following command:
fabric-ca-client enroll -u https://<peer_admin_enroll_id>:

<peer_admin_enroll_password>@<ca_url_with_port> --caname <ca_name> -M $HOME/path/to/peer-admin/msp --
tls.certfiles <ca_tls_cert_path>
For example:
fabric-ca-client enroll -u https://peeradmin:peeradminpw@9.30.94.174:30167 --caname ca -M

$HOME/fabric-ca-client/peer-admin/msp --tls.certfiles $HOME/fabric-ca-client/catls/tls.pem
After this command completes successfully, it generates a new MSP folder in the directory that you specified by using the -M
flag. This directory contains the certificates that you need to use to operate your components. You can verify that the enroll
command worked by using a tree command. Navigate to the directory where you stored your certificates. A tree command
should generate a result similar to the following structure:
tree
.
├── ca-admin
│ ├── fabric-ca-client-config.yaml
│ └── msp
│ │ └── 9-30-250-70-30395-SampleOrgCA.pem
│ │ └── 425947b767936a8f31780390cbc399cae48663b643e906ceb6944500d57b322c_sk
│ └── user
├── catls
│ └── tls.pem
├── orderer-admin
│ └── msp
│ │ └── 9-30-250-70-30395-SampleOrgCA.pem
│ │ └── 30a12af2359cd96ec02ff5f47ad7793d2fefe3cde2be574bace18b24d36ba015_sk
│ └── user
└── peer-admin
└── msp
├── IssuerPublicKey
├── IssuerRevocationPublicKey

├── cacerts
│ └── 9-30-250-70-30395-SampleOrgCA.pem
├── keystore
│ └── c9c20a57a3afa70541bee6cec52ea1f654a8b116fcca35e1fbf27e60f1f989ec_sk
├── signcerts
│ └── cert.pem
└── user
Important: You will need to return to this folder when you create your organization MSP definition and configuration files.
Registering the component identity with the TLS CA

When you created your CA, a TLS CA was deployed along with your default CA. You also need to register the ordering node or
peer with your TLS CA. To do this, you will first need to enroll by using the admin of the TLS CA. Change
$FABRIC_CA_CLIENT_HOME to a directory where you want to store your TLS CA admin certificates.
mkdir tlsca-admin
export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca-client/tlsca-admin
Run the command below to enroll as your admin against the TLS CA. The enroll ID and password of your TLS CA admin are the
same as your default CA. As a result, the command below is the same as you used to enroll as your CA admin only with the
name of your TLS CA. Your TLS CA name is the TLS CA Name value from the CA settings panel in your console, or the value of
the "tlsca_name" returned by the Create a CA API.
fabric-ca-client enroll -u https://<enroll_id>:<enroll_password>@<ca_url_with_port> --caname

<tls_ca_name> --tls.certfiles <ca_tls_cert_path>
A real call might look similar to the following example:
fabric-ca-client enroll -u https://admin:adminpw@9.30.94.174:30167 --caname tlsca --tls.certfiles

$HOME/fabric-ca-client/catls/tls.pem
After you enroll, you have the necessary certificates to register your component with the TLS CA. Run the following command to
register the ordering node or peer:
fabric-ca-client register --caname <ca_name> --id.name <name> --id.affiliation org1.department1 --

id.type peer --id.secret <password> --tls.certfiles <ca_tls_cert_path>
This command is similar to the one that you used to register the component identity with the CA, except that you need to use the
TLS CA name. If you are deploying an ordering node instead of a peer, set --id.type to orderer instead of peer . You must
provide this identity a different username and password than the one that you used against your default CA. A real register might
look similar to the command below:
fabric-ca-client register --caname tlsca --id.affiliation org1.department1 --id.name peertls --

id.secret peertlspw --id.type peer --tls.certfiles $HOME/fabric-ca-client/catls/tls.pem
Important: You need to save the "enrollid" and "enrollsecret" from the command above for when you create
your configuration file.
Troubleshooting
Problem: Error when running the enroll command

When running the Fabric CA client enroll command, it is possible the command fails with the following error:
Error: Failed to read config file at '/Users/chandra/fabric-ca-client/ca-admin/fabric-ca-client-

config.yaml': While parsing config: yaml: line 42: mapping values are not allowed in this context
Solution:
This error can occur when your Fabric CA client tries to enroll but cannot connect to your CA. This can happen if:
Your enroll command contains an extra https:// on the -u parameter.

Your CA name is incorrect.
Your username or password is incorrect.
Review the parameters that you specified on your enroll command and ensure that none of these conditions exist.
Problem: Error with CA URL when running the enroll command

The Fabric CA client enroll command can fail if the enrollment URL, the -u parameter value, contains a special character. For
example, the following command with the enroll ID and password of admin:C25A06287!0 ,
./fabric-ca-client enroll -u https://admin:C25A06287!0@ash-zbc07c.4.secure.blockchain.ibm.com:21241 -

-tls.certfiles $HOME/fabric-ca-remote/cert.pem --caname PeerOrg1CA
will fail and produce the following error:
!pw@9.12.19.115: event not found
Solution:
You need to either encode the special character or surround the URL with the single quotation marks. For example, ! becomes
%21 , or the command looks like:
./fabric-ca-client enroll -u 'https://admin:C25A06287!0@ash-zbc07c.4.secure.blockchain.ibm.com:21241'

--tls.certfiles $HOME/fabric-ca-remote/cert.pem --caname PeerOrg1CA
Creating an organization MSP definition

You can use the APIs to create an organization MSP definition by calling POST /ak/api/v2/components/msp. This MSP
contains certificates that define your organization in a blockchain consortium, as well as the admin certificates that you can use
to operate your network. If you followed the step above, you have already generated the certificates that are needed to create an
organization MSP. Use the following steps to complete the request body of the API call.
1. Select an MSP ID for your organization. The MSP ID is the formal name of your organization within the consortium. The
MSP ID used to create the organization MSP needs to be the same that you use to deploy your peers.
2. Select a display name for your MSP.
3. You need to provide the signCert, in base64 format, of your organization administrator that you registered and enrolled by
using the Fabric CA client.
Navigate to the MSP directory that was created when you generated certificates by using your organization administrator.
cd $HOME/fabric-ca-client/peer-admin/msp
In this MSP directory, open the signCert file of the new user and convert it to base64 format by using the following
commands:

cat $HOME/<path-to-peer-admin>/msp/signcerts/cert.pem | base64 $FLAG
Note: It is important that the string generated by using the command above is formatted as a single line. It should look
similar to:
$
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlFbERDQ0EzeWdBd0lCQWdJUUFmMmo2MjdLZGNpSVE0dHlTOCs4a1RBTkJna3Foa2lHOXc
C
Not like this:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlFbERDQ0EzeWdBd0lCQWdJUUFmMmo2MjdL
ZGNpSVE0dHlTOCs4a1RBTkJna3Foa2lHOXcwQkFRc0ZBREJoDQpNUXN3Q1FZRFZRUUdFd0pWVXpF
Vk1CTUdBMVVFQ2hNTVJHbG5hVU5sY25RZ1NXNWpNUmt3RndZRFZRUUxFeEIzDQpkM2N1WkdsbmFX
VEFlRncweE16QXpNRGd4TWpBd01EQmFGdzB5TXpBek1EZ3hNakF3TURCYU1FMHhDekFKQmdOVkJB
WVRBbFZUDQpNUlV3RXdZRFZRUUtFd3hFYVdkcFEyVnlkQ0JKYm1NeEp6QWxCZ05WQkFNVEhrUnBa
For example:
cat $HOME/fabric-ca-client/peer-admin/msp/signcerts/cert.pem | base64 $FLAG
This command prints a string that is similar to the following example:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNuRENDQWtPZ0F3SUJBZ0lVTXF5VDhUdnlwY3lYR2sxNXRRY3hxa1RpT
G9Nd0NnWUlLb1pJemowRUF3SXcKYURFTTlEKaFhTTzRTWjJ2ZHBPL1NQZWtSRUNJQ3hjUmZVSWlkWHFYWGswUGN1OHF2aCtW
SkhGeHBLUnQ3dStHZDMzalNSLwotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
Provide this string to the admins field of the API request.
4. You also need to provide the root certificate of your CA. This certificate was created when you generated certificates by
using your CA admin.
Navigate to the CA admin MSP directory.
cd $HOME/fabric-ca-client/ca-admin/msp
In this directory, open the cacerts folder and convert the certificate inside into base64 format by using the following
commands:
cat $HOME/<path-to-ca-admin>/msp/cacerts/<ca_root_cert>.pem | base64 $FLAG
This prints the root cert as a base64 encoded sting.
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNGekNDQWIyZ0F3SUJBZ0lVQmZnZzcvVnIrL25OVEFNQlQ4UUtHL00wQ
U8wd0NnWUlLb1pJemowRUF3SXcKYURFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1a
E1SUXdFZ1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVJrd0Z3WURWUVFERXhCbVlXS
nlhV010ClkyRXRjMlZ5ZG1WeU1CNFhEVEU1TURVd016RXpNamt3TUZvWERUTTBNRFF5T1RFek1qa3dNRm93YURFTE1Ba0cKQ
TFVRUJoTUNWVk14RnpBVkJnTlZCQWdURGs1dmNuUm9JRU5oY205c2FXNWhNUlF3RWdZRFZRUUtFd3RJZVhCbApjbXhsWkdkb
GNqRVBNQTBHQTFVRUN4TUdSbUZpY21sak1Sa3dGd1lEVlFRREV4Qm1ZV0p5YVdNdFkyRXRjMlZ5CmRtVnlNRmt3RXdZSEtvW
kl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVXMUtvN2lWeVE2VWkwdDVqbU5KaWVuSUwKR3pNM1BDWHlhL2VSQ0NWMmFQb0dTZ
1lrVUg2UWN5RjAzbFlMZFU4Y0drNTQ0alViVC9KT1lYeVgzTWc4bHFORgpNRU13RGdZRFZSMFBBUUgvQkFRREFnRUdNQklHQ
TFVZEV3RUIvd1FJTUFZQkFmOENBUUV3SFFZRFZSME9CQllFCkZDK2lJR0NSb2Zvb3FsVkZoU3dOMmk2MXNJaVBNQW9HQ0NxR
1NNNDlCQU1DQTBnQU1FVUNJUURTYW9RL1E0QzkKbFl1VGNhVXVHb3d6YmhUZHBuN2F3S2lHN1Nvd2lSQXVld0lnUWlyM3RNR
3IvYWo2aU5lRXJFN2NyOVowQ0gvTwp3QnNQcWd4RVR3MjVqZUU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
Provide this string to the root_certs field of the API request.

5. You should also provide the root certificate of your TLS CA. The TLS root certificate allows your peers to participate in
gossip on a channel.
Navigate to the MSP directory that was generated when you enrolled your TLS CA admin.
cd $HOME/fabric-ca-client/tlsca-admin/msp
In this directory, open the cacerts folder and convert the certificate inside into base64 format by using the following
commands:
cat $HOME/<path-to-tlsca-admin>/msp/cacerts/<tls_root_cert>.pem | base64 $FLAG
The command prints the TLS CA root cert as a base64 encoded sting.
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNHRENDQWI2Z0F3SUJBZ0lVWUVQWnprNXV2b3dobEtacG5JMXplODdIQ
Ulnd0NnWUlLb1pJemowRUF3SXcKWFRFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1a
E1SUXdFZ1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVE0d0RBWURWUVFERXdWMGJIT
mpZVEFlCkZ3MHhPVEExTURNeE16STVNREJhRncwek5EQTBNamt4TXpJNU1EQmFNRjB4Q3pBSkJnTlZCQVlUQWxWVE1SY3cKR
lFZRFZRUUlFdzVPYjNKMGFDQkRZWEp2YkdsdVlURVVNQklHQTFVRUNoTUxTSGx3WlhKc1pXUm5aWEl4RHpBTgpCZ05WQkFzV
EJrWmhZbkpwWXpFT01Bd0dBMVVFQXhNRmRHeHpZMkV3V1RBVEJnY3Foa2pPUFFJQkJnZ3Foa2pPClBRTUJCd05DQUFRdSs2U
nZWd2w5T2dDVlAraEVxbjVxdExRVG9LWkw4a1lic0pOeU1JbERoc3hlNWx6cW1zQkoKbTk2eUR2TVV6OSsxL2pzb1M4M1JqM
VAwc3M2TnJNb3FvMXd3V2pBT0JnTlZIUThCQWY4RUJBTUNBUVl3RWdZRApWUjBUQVFIL0JBZ3dCZ0VCL3dJQkFUQWRCZ05WS
FE0RUZnUVVnUEc4anJEK1BxVjdoelc3WDlsbTFrMS91WjR3CkZRWURWUjBSQkE0d0RJY0VxVGJESW9jRUNwbnBkVEFLQmdnc
Whrak9QUVFEQWdOSUFEQkZBaUVBenk3cHJZaVMKQmlDVWdYeWRkY09WMm9mZmtqaEI0N091QXFjQWNqZS9SWkVDSUdKZFgzZ
1ErTDRIN3duY1RoZkwrenU1ejV1UApGUWhXTmlNS3hQWEYrZnYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
Provide this string to the tls_root_certs field of the API request.
Creating a configuration file

You need to complete a configuration file in order to create a peer or ordering node by using the APIs. This file is provided to the
API as the config object in the request body of the API call. If you are creating multiple ordering nodes, you need to provide a
configuration file for each node that you want to create in an array to the API request. For example, for a five node raft ordering
service, you need to create an array of five configuration files. You can provide the same file for each node as long as the
enrollID's that you provide have a sufficiently high enrollment limit. You need to deploy a CA and follow the steps to register and
enroll the required identities before you complete the file.
The template for the configuration file can be found below:
{
"enrollment": {
"component": {
"cahost": "",
"caport": "",
"caname": "",
"catls": {
"cacert": ""
},
"enrollid": "",
"enrollsecret": "",
"admincerts": [""]
},
"tls": {
"cahost": "",
"caport": "",
"caname": "",
"catls": {
"cacert": ""
},
"enrollid": "",

"enrollsecret": "",
"csr": {
"hosts": [""]
}
}
}
}
Copy this entire file into a text editor where you can edit it and save it to your local file system as a JSON file. Use the steps
below to complete this configuration file and use it to deploy an ordering service or peer.
Retrieve the CA connection information

First, we need to provide the connection information of your CA on the IBM Blockchain Platform. You can use the console UI or
the APIs to get the necessary information about your CA.
If you are using the IBM Blockchain Platform console: Open the CA in your console and click Settings, then the Export button
to export the CA information to a JSON file. You can use the values from this file to complete your configuration file.
If your are using the APIs: You can call GET /ak/api/v2/components to get the connection information of your CA. If you
created the CA with the Create a Fabric CA API, you can also find the necessary information in the response body.
The "cahost" and "caport" values are visible in the ca_url field in the response body or CA JSON file that you exported.
For example, if your ca_url is https://9.30.94.174:30167, the value of the "cahost" would be 9.30.94.174 and the
"caport" would be 30167.
The "caname" is the name of the CA that was specified when you deployed the CA. This is the value of theca_name field in
the response body or the exported JSON file.
The "cacert" is the base64-encoded TLS certificate of your CA. This is the value of the pem field in the response body or
the exported JSON file.
The fields in the "tls" section below require the same information as you passed to the component sections above,
except you need to use the value of the CA TLS instance name that is specified during CA deployment. Replace caname
with the value of tlsca_name in the response body or the exported JSON file. Use the same TLS cert for the "cacert"
value.
"tls": {
"cahost": "",
"caport": "",
"caname": "",
"catls": {
"cacert": ""
Provide your component enroll ID and secret

1. Paste the name and secret you used to register your component with your default CA as the "enrollid" and
"enrollsecret" in the configuration file, under the "component" section:
"component": {...
},
"enrollid": "peer1",
"enrollsecret": "peer1pw",
2. Paste the name and secret you used to register your component with your tls CA as the "enrollid" and
"enrollsecret" in the configuration file, under the "tls" section:
"tls": {...
},

"enrollid": "peertls",
"enrollsecret": "peertlspw",
Provide the signCert of your organization administrator

Navigate to the MSP directory that was created when your generated certificates using your organization administrator.
cd $HOME/fabric-ca-client/peer-admin/msp
In this MSP directory, open the signCert file of the new user and convert it to base64 format by using the following commands:
cat $HOME/<path-to-peer-admin>/msp/signcerts/cert.pem | base64 $FLAG
Note: It is important that the string generated by using the command above is formatted as a single line. It should look similar
to:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlFbERDQ0EzeWdBd0lCQWdJUUFmMmo2MjdLZGNpSVE0dHlTOCs4a1RBTkJna
3Foa2lHOXcwQkFRc0ZBREJoDQpNUXN3Q1FZRFZRUUdFd0pWVXpFVk1CTUdBMVVFQ2hNTVJHbG5hVU5sY25RZ1NXNWpNUmt3RndZRF
ZRUUxFeEIzDQpkM2N1WkdsbmFXTmxjblF1WTI5dE1TQXdIZ1lEVlFRREV4ZEVhV2RwUTJWeWRDQkhiRzlpWVd3Z1VtOXZkQ0JEDQp
RVEFlRncweE16QXpNRGd4TWpBd01EQmFGdzB5TXpBek1EZ3hNakF3TURCYU1FMHhDekFKQmdOVkJBWVRBbFZUDQpNUlV3RXdZRFZR
UUtFd3hFYVdkcFEyVnlkQ0JKYm1NeEp6QWxCZ05WQkFNVEhrUnBaMmxEWlhKMElGTklRVElnDQpVMlZqZFhKbElGTmxjblpsY2lC
Not like this:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlFbERDQ0EzeWdBd0lCQWdJUUFmMmo2MjdL
ZGNpSVE0dHlTOCs4a1RBTkJna3Foa2lHOXcwQkFRc0ZBREJoDQpNUXN3Q1FZRFZRUUdFd0pWVXpF
Vk1CTUdBMVVFQ2hNTVJHbG5hVU5sY25RZ1NXNWpNUmt3RndZRFZRUUxFeEIzDQpkM2N1WkdsbmFX
VEFlRncweE16QXpNRGd4TWpBd01EQmFGdzB5TXpBek1EZ3hNakF3TURCYU1FMHhDekFKQmdOVkJB
WVRBbFZUDQpNUlV3RXdZRFZRUUtFd3hFYVdkcFEyVnlkQ0JKYm1NeEp6QWxCZ05WQkFNVEhrUnBa
For example:
cat $HOME/fabric-ca-client/peer-admin/msp/signcerts/cert.pem | base64 $FLAG
This command prints a string that is similar to the following example:
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNuRENDQWtPZ0F3SUJBZ0lVTXF5VDhUdnlwY3lYR2sxNXRRY3hxa1RpTG9Nd
0NnWUlLb1pJemowRUF3SXcKYURFTTlEKaFhTTzRTWjJ2ZHBPL1NQZWtSRUNJQ3hjUmZVSWlkWHFYWGswUGN1OHF2aCtWSkhGeHBLU
nQ3dStHZDMzalNSLwotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
Copy this string to the "admincerts" field under the component section in the configuration file.
CSR (Certificate Signing Request) hosts

You have the option of providing a custom domain to your component by using the "csr" section of the components file.
"csr": {
"hosts": [""]
}
This section is provided for advanced users to specify a custom hostname that can be used to communicate with the peer. Most
users can leave this section blank.
Completing the configuration file

After you completed all the steps above, your updated configuration file might look similar to the following example:

{
"enrollment": {
"component": {
"cahost": "9.30.20.70",
"caport": "32129",
"caname": "ca",
"catls": {
"cacert":
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNGakNDQWIyZ0F3SUJBZ0lVTmlUbkdTandSdU1JVXhpWGcwMGZZWXhPSndJ
d0NnWUlLb1pJemowRUF3SXcKYURFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ
1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVJ0Z3WURWUVFERXhCbVlXSnlhV010ClkyRXRj
MlZ5ZG1WeU1CNFhEVEU0TVRFeE5qRTJNVEF3TUZvWERUTXpNVEV4TWpFMk1UQXdNRm93YURFTE1Ba0cKQTFVRUJoTUNWVk14RnpBV
kJnTlZCQWdURGs1dmNuUm9JRU5oY205c2FXNWhNUlF3RWdZRFZRUUtFd3RJZVhCbApjbXhsWkdkbGNqRVBNQTBHQTFVRUN4TUdSbU
ZpY21sak1Sa3dGd1lEVlFRREV4Qm1ZV0p5YVdNdFkyRXRjMlZ5CmRtVnlNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFF
nQUU1dlBucDJUNTdkY2hTOGRLNExsMFJRZEEKd284RmJsMzBPcnBGdWFHUld5TFl4eGcxcVFTemhUY3hTcGtHZjh3a1FzVDVFb01l
SWcrRytldjBOU01FUTZORgpNRU13RGdZRFZSMFBBUUgvQkFRREFnRUdNQklHQTFVZEV3RUIvd1FJTUFZQkFmOENBUUV3SFFZRFZSM
E9CQllFCkZMd2d1N0J3Uk9lQ2hzV2hWQWptMTdmalh1eVBNQW9HQ0NxR1NNNDlCQU1DQTBjQU1FUUNJR0FCRmNSdXhtSkIKY3c4OT
JJOXhPS3YxVmYyT0JHZUh5N2pFQzRBRm5najFBaUJqdHFvdjBXMXdxZjhwcGttYkxIQkJoWW1vS3ZqRwo4bDQyeVQ5bWYxWVQrZz0
9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
},
"enrollid": "peer1",
"enrollsecret": "peer1pw",
"admincerts": [
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMzRENDQW9PZ0F3SUJBZ0lVS2Vib0drZEJqenM5bllRbkVQTWp0VG56YTVr
1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVJrd0Z3WURWUVFERXhCbVlXSnlhV010ClkyRX
RjMlZ5ZG1WeU1CNFhEVEU0TVRFeE9URTNNRE13TUZvWERURTVNVEV4T1RFM01EZ3dNRm93ZmpFTE1BaKQTFVRUJoTUNWVk14RnpBV
kJnTlZCQWdURGs1dmNuUm9JRU5oY205c2FXNWhNUlF3RWdZRFZRUUtFd3RJZVhCbApjbXhsWkdkbGNqRXVNQXNHQTFVRUN4TUVkWE
5sY2pBTEJnTlZCQXNUQkc5eVp6RXdFZ1lEVlFRTEV3dGtaWEJoCmNuUnRaVzUwTVRFUU1BNEdBMVVFQXhNSFlXUnRhVzR4Y0RCWk1
CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUgKQTBJQUJLbjUwdEU5TmpZb0RFNDBqalh6RUJ2T2c3Y3RtOElRd0laMnRkS29iNEww
VVhKdSs1Tkt5S2dyUk9vbApWcjBmQmg5cWZWMjl4Nms0T2dmMFNiVklBZWlqZ2ZRd2dmRXdEZ1lEVlIwUEFRSC9CQVFEQWdlQU1Bd
0dBMVVkCkV3RUIvd1FDTUFBd0hRWURWUjBPQkJZRUZOYWFkV0VzcGp2Smk1akpiVktiS2M3ZU1wUmhNQjhHQTFVZEl3UVkKTUJhQU
ZMd2d1N0J3Uk9lQ2hzV2hWQWptMTdmalh1eVBNQ2NHQTFVZEVRUWdNQjZDSEdOb1lXNWtjbUZ6TFcxaQpjQzV5WVd4bGFXZG9MbWx
pYlM1amIyMHdhQVlJS2dNRUJRWUhDQUVFWEhzaVlYUjBjbk1pT25zaWFHWXVRV1ptCmFXeHBZWFJwYjI0aU9pSnZjbWN4TG1SbGNH
RnlkRzFsYm5ReElpd2lhR1l1Ulc1eWIyeHNiV1Z1ZEVsRUlqb2kKWVdSdGFXNHhjQ0lzSW1obUxsUjVjR1VpT2lKMWMyVnlJbjE5T
UFvR0NDcUdTTTQ5QkFNQ0EwY0FNRVFDSURGeApDYzE1bDZUZ1dqYnhSZzlmNjczOGV0K0NZZ1I3VVpGR200VHdoQk5jQWlBNmtUMF
FwbDV6WnBUN3BzM0dySXlVCmEydDRHSTQ5ZTdjUm5PMmdrSzl6Z3c9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="
]
},
"tls": {
"cahost": "9.30.20.70",
"caport": "32129",
"caname": "tlsca",
"catls": {
"cacert":
"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNGakNDQWIyZ0F3SUJBZ0lVTmlUbkdTandSdU1JVXhpWGcwMGZZWXhPSndJ
1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVJrd0Z3WURWUVFERXhCbVlXSnlhV010ClkyRX
RjMlZ5ZG1WeU1CNFhEVEU0TVRFeE5qRTJNVEF3TUZvWERUTXpNVEV4TWpFMk1UQXdNRm93YURFTE1Ba0cKQTFVRUJoTUNWVk14Rnp
BVkJnTlZCQWdURGs1dmNuUm9JRU5oY205c2FXNWhNUlF3RWdZRFZRUUtFd3RJZVhCbApXhsWkdkbGNqRVBNQTBHQTFVRUN4TUdSbU
ZpY21sak1Sa3dGd1lEVlFRREV4Qm1ZV0p5YVdNdFkyRXRjMlZ5CmRtVnlNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFF
nQUU1dlBucDJUNTdkY2hTOGRLNExsMFJRZEEKd284RmJsMzBPcnBGdWFHUld5TFl4eGcxcVFTemhUY3hTcGtHZjh3a1FzVDVFb01l
SWcrRytldjBOU01FUTZORgpNRU13RGdZRFZSMFBBUUgvQkFRREFnRUdNQklHQTFVZEV3RUIvd1FJTUFZQkFmOENBUUV3SFFZRFZSM
E9CQllFCkZMd2d1N0J3Uk9lQ2hzV2hWQWptMTdmalh1eVBNQW9HQ0NxR1NNNDlCQU1DQTBjQU1FUUNJR0FCRmNSdXhtSkIKY3c4OT
JJOXhPS3YxVmYyT0JHZUh5N2pFQzRBRm5najFBaUJqdHFvdjBXMXdxZjhwcGttYkxIQkJoWW1vS3ZqRwo4bDQyeVQ5bWYxWVQrZz0
9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
},
"enrollid": "peertls",
"enrollsecret": "peertlspw",
"csr": {
"hosts": [
]
}
}
}
}

You can leave the other fields blank. After you complete this file, you can pass this file as the config field to the request body
of the Create an ordering service or Create a peer API.
Importing an admin identity into the IBM Blockchain Platform console

If you want to use the IBM Blockchain Platform console to operate your blockchain components, you must import your
administrator identity into your console wallet. Open the wallet panel in your console. Click the Add identity button on the
overview screen. Clicking this button opens up a side panel that allows you to add an identity's signing certificate and private key
directly to the console.
Name: Enter a display name for the identity that is used for your reference only.
Certificate: Upload your admin's signing certificate. If you followed the instructions above, you can find this key in the
$HOME/fabric-ca-client/peer-admin/msp/signcerts/ folder.
Private Key: Upload your admins private key. If you followed the instructions above, you can find this key in the
$HOME/fabric-ca-client/peer-admin/msp/keystore/ folder.
After you import your admin identity, you can associate this identity with the components that you create. You can then use the
console to operate your network.

Hyperledger Fabric
IBM® Blockchain network is built on the Hyperledger Fabric stack, one of the blockchain projects within the Linux Foundation's
Hyperledger Project. It is a "permissioned" network where all users and components have known identities. Sign/verify logic is
implemented at every communication touchpoint, and transactions are consented upon through a series of endorsement and
validation checks. In this sense, it differs greatly from traditional blockchain implementations that promote anonymity and are
forced to rely on cryptocurrencies and heavy compute obligations to validate transactions.
Hyperledger Fabric offers a modular architecture to extend the scalability and performance. This topic introduces some key
components in Hyperledger Fabric. For a complete introduction on Hyperledger Fabric, see Hyperledger Fabric documentation.
Peers
At a physical level, a blockchain network is comprised primarily of peer nodes (or, simply, peers). Peers are the fundamental
elements of the network because they host ledgers and smart contracts (which are contained in "chaincode". More accurately,
the peer hosts instances of the ledger, and instances of smart contracts. Because smart contracts and ledgers are used to
encapsulate the shared processes and shared information in a network, respectively, these aspects of a peer make them a good
starting point to understand what a Fabric network actually does.
To learn more about peers specifically, check out this document focusing just on peers from the Fabric community
documentation.
As a platform for permissioned blockchain networks, Hyperledger Fabric includes a modular Certificate Authority (CA)
component for managing the network identities of all member organizations and their users. The requirement for a permissioned
identity for every user enables ACL-based control over network activity, and guarantees that every transaction is ultimately
traceable to a registered user.
The CA issues a root certificate (rootCert) to each member (organization or individual) that is authorized to join the
network.
The CA also issues an enrollment certificate (eCert) to each member component, server-side applications and
occasionally users.
Each enrolled user is also granted an allocation of transaction certificates (tCerts). Each tCert authorizes one network
transaction.
This certificate-based control over network membership and actions enables members to restrict access to private and
confidential channels, applications, and data, by specific user identities.
For more information about the Hyperledger Fabric Certificate Authority component, see Fabric CA User’s Guide.
Membership Service Provider

Hyperledger Fabric includes a Membership Service Provider (MSP) component to offer an abstraction of all cryptographic
mechanisms and protocols behind issuing and validating certificates, and user authentication. The MSP is installed on each
channel peer to ensure that transaction requests that are issued to the peer originate from an authenticated and authorized user
identity.
For more information about the Hyperledger Fabric Membership Services Provider component, see Membership in the
Hyperledger Fabric documentation.
Ordering service

In other distributed blockchains, such as Ethereum and Bitcoin, there is no central authority that orders transactions and sends
them out to peers. Hyperledger Fabric, the blockchain that the IBM Blockchain Platform is based on, work differently. It features
a node called an orderer.
Orderers are key components in a network because they perform a few essential functions:
It literally orders the blocks of transactions that are sent to the peers to be written to their ledgers, and this process is
called "ordering". If these transactions were instead bundled and ordered at the peers themselves, it would increase the
possibility of one peer writing a transaction to its ledger where another peer did not, creating a state fork.
It maintains the orderer system channel, the place where the consortium, the list of peer organizations permitted to
create channels, resides.
It performs important identity validation checks. For example, if an organization tries to create a channel when it is not a
member of the orderer's consortium, the request will be denied. Orderers also validate against behaviors in transaction
channels, such as the permissions for changing a channel configuration.
Hyperledger Fabric currently uses an implementation of the Raft protocol for its ordering service. For more information about the
ordering service, see The Ordering Service.
The Fabric SDKs

The Hyperledger Fabric SDKs enable application developers to build applications that interact with a blockchain network. These
SDKs help facilitate applications to manage the lifecycle of channels and chaincode.
Hyperledger Fabric delivers both a Node.js SDK and Java SDK, and provides the following functions to interact with the
blockchain network:
Register and enroll users

Create channels
Join peers to a channel
Update system channel or application channel configuration
Install chaincode on peers
Instantiate chaincode on a channel
Upgrade chaincode on a channel
Call chaincode functions to update the ledger
Query the ledger for specific transactions, blocks or keys
Monitor events on a channel (for example, successful commitment of a transaction)
For more information about Fabric SDKs, see Hyperledger Fabric SDKs in Hyperledger Fabric documentation.
Transaction flow
To ensure data consistency and integrity, Hyperledger Fabric implements multiple checkpoints throughout the transaction flow,
including client authentication, endorsement, ordering, and commitment to the ledger.
Figure 1 depicts the transaction flow on a Hyperledger Fabric blockchain network:
Figure 1. Transaction flow on a Hyperledger Fabric network
On a Hyperledger Fabric network, the flow of data for queries and transactions is initiated by a client-side application by
submitting a transaction request to a peer on a channel. The initial flow of data across the network is common to both queries
and transactions:
1. Using APIs available in the SDK, a client application signs and submits a transaction proposal to the appropriate endorsing
peers on the specified channel. This initial transaction proposal is a request for endorsement.

2. Each peer on the channel verifies the identity and authority of the submitting client, and (if valid) runs the specified
chaincode against the supplied inputs. Based on the transaction results and the endorsement policy for the invoked
chaincode, each peer returns a signed YES or NO response to the application. Each signed YES response is an
endorsement of the transaction.
At this point in the transaction flow, the process diverges for queries and transactions. If the proposal called a query function
in the chaincode, the application returns the data to the client. If the proposal called a function in the chaincode to update
the ledger, the application continues with the following steps:
3. The application forwards the transaction, which includes the read/write set and endorsements, to theordering service.
4. The transaction is then relayed to the ordering service. All channel peers validate each transaction in the block by applying
the chaincode-specific Validation Policy and running a Concurrency Control Version Check.
Any transaction that fail the validation process is marked as invalid in the block, and the block is appended to the
channel's ledger.
All valid transactions update the state database accordingly with the modified key/value pairs.
The gossip data dissemination protocol continually broadcasts ledger data across the channel to ensure synchronized ledgers
among peers. For more information, see Gossip data dissemination protocol in Hyperledger Fabric documentation.
For a step-by-step introduction on transaction flow, see Transaction Flow in Hyperledger Fabric documentation.

Kubernetes
The IBM Blockchain Platform allows you to provision blockchain components into your Kubernetes cluster. Kubernetes is an
open-source system for automating deployment, scaling, and management of containerized applications.
Kubernetes provides a container-centric management environment. It orchestrates computing, networking, and storage
infrastructure on behalf of user workloads. This provides much of the simplicity of Platform as a Service (PaaS) with the flexibility
of Infrastructure as a Service (IaaS), and enables portability across infrastructure providers.
The following diagram explains the architecture of Kubernetes. For more explanation about nodes, containers, and pod, see the
Key Kubernetes objects section below.
Figure 1. Kubernetes architecture diagram
Key Kubernetes objects

Cluster
A set of machines, called nodes, that run containerized applications managed by Kubernetes. A cluster has several worker
nodes and at least one master node.
Node
A node is a worker machine in Kubernetes. A node may be a VM or physical machine, depending on the cluster. Each node
contains the services necessary to run pods and is managed by the master components. The services on a node include
the container runtime, kubelet and kube-proxy . For more information, see the Kubernetes Node section in the
Kubernetes documentation.
Container
A lightweight and portable executable image that contains software and all of its dependencies. Containers decouple
applications from underlying host infrastructure to make deployment easier in different cloud or OS environments, and for
easier scaling.
Pod
The smallest and simplest Kubernetes object. A Pod represents a set of running containers on your cluster. A Pod is typically
set up to run a single primary container. It can also run optional sidecar containers that add supplementary features like
logging. Pods are commonly managed by a Deployment. For more information, see the Kubernetes Pod section in the
Kubernetes documentation.
IBM Cloud Kubernetes Service

IBM Cloud Kubernetes Service delivers powerful tools by combining Docker containers, the Kubernetes technology, an intuitive
user experience, and built-in security and isolation to automate the deployment, operation, scaling, and monitoring of
containerized apps in a cluster of compute hosts. You can use the IBM Cloud Kubernetes Service to deploy clusters using open
source Kubernetes and the OpenShift Container Platform.
For more information about IBM Cloud Kubernetes Service, see the following topics in IBM Cloud Kubernetes Service
documentation:
Understanding the IBM Cloud Kubernetes Service

Why IBM Cloud Kubernetes Service

Defining your Kubernetes strategy

IBM Blockchain Platform locations
IBM Cloud® is hosted worldwide in various locations. Locations are data centers within a geographic area that is accessed by an
endpoint. IBM Blockchain Platform deploys blockchain networks within IBM Cloud globally in different locations. When you
create IBM Blockchain Platform service instance in IBM Cloud, your blockchain network and network resources are created and
stored in the IBM Cloud location where you create the service instance in.
IBM Blockchain Platform for IBM Cloud

To deploy the IBM Blockchain Platform for IBM Cloud, you need to select two locations:
1. You need to deploy a Kubernetes cluster on IBM Cloud. You can deploy the cluster to any geography supported by the
IBM Kubernetes service or Red Hat OpenShift on IBM Cloud. For more information, see the list of locations for the IBM
Kubernetes service or locations for OpenShift on IBM Cloud.
Figure 1. Kubernetes cluster on IBM Cloud locations
2. After you deploy a cluster on IBM Cloud, you need to deploy an instance of the IBM Blockchain Platform. The IBM
Blockchain Platform operational tooling can be deployed in each of the regions in the table below:
Geography Country IBM Blockchain Platform operational tools region
Asia Pacific Australia Sydney
Asia Pacific Japan Tokyo
Europe Germany Frankfurt
Europe United Kingdom London
North America United States Dallas
North America United States Washington, D.C.
Table 1. IBM Blockchain Platform for IBM Cloud locations
You can link an instance of the IBM Blockchain Platform operational tooling to a cluster that is deployed at any location.
However, all nodes provisioned by the console will be deployed in the location of the cluster. For example, if the Kubernetes
cluster is located in Toronto and the linked console is in Washington, D.C., when you use the console to deploy a peer, the peer
will reside in Toronto. For more information about the relationship between the operational tools and your cluster, see the IBM
Blockchain Platform for IBM Cloud architecture reference.

Glossary
This topic defines IBM® Blockchain Platform-specific terms that appear in this documentation. For a deeper understanding of
terms, and for a glossary of terms that relate to Hyperledger Fabric concepts, refer to the Hyperledger Fabric glossary.
Approve
Referring to a step in the Hyperledger Fabric v2.x smart contract lifecycle, a smart contract definition is approved by
organizations on the channel. After the number of approvals that are specified in the channel lifecycle endorsement policy are
satisfied, the smart contract definition can be committed to a channel, and the peers where it is installed can begin to process
requests.
Asset
Tangible or intangible goods, services, or property that are represented as an item that is traded on the blockchain network.
Block
An ordered set of transactions, which is cryptographically linked to the preceding block on a channel.
CA
An abbreviation of "Certificate Authority", this is the component that issues certificates to all the participating members. These
certificates represent a member’s identity. All entities in the network (peers, ordering nodes, clients, and so on) must have an
identity to communicate, authenticate, and ultimately transact. These identities are required for any direct participation in the
blockchain network.
Chain
The ledger’s chain is a transaction log structured as hash-linked blocks of transactions. Peers receive blocks of transactions from
the ordering service, mark the block’s transactions as valid or invalid based on endorsement policies and concurrency violations,
and append the block to the hash chain on the peer’s file system.
Chaincode
Where smart contracts contain the business logic that governs the interactions for a set of assets, "chaincode" describes the
larger set of packages and infrastructure that encompass the smart contract.
Channel
Consisting of a subset of network members who want to transact privately. Channels provide data isolation and confidentiality by
allowing the members of a channel to establish specific rules and a separate ledger that only channel members can access.
Peers, which are the nodes that function as transaction endpoints for organizations, are joined to channels.
Client
The client represents the entity that acts on behalf of a user. It must connect to a peer for communicating with the blockchain.
The client might connect to any peer of its choice. Clients create and thus invoke transactions. The client submits an actual
transaction invocation to the endorsers, and broadcasts transaction proposals to the ordering service.
Commit

Referring to a step in the Hyperledger Fabric v2.x smart contract lifecycle, after the number of approvals that are specified in the
channel lifecycle endorsement policy are satisfied, the smart contract definition can be committed to a channel, and the peers
where it is installed can begin to process requests.
Connection profile
A connection profile is used by the Fabric Client SDKs to connect to the network. A connection profile can be downloaded from
the Organizations tile.
Consensus
A collaborative process to keep the ledger transactions synchronized across the network. Consensus ensures that ledgers are
updated only when the appropriate participants approve transactions, and that ledgers are updated with the same transactions
in the same order. There are many different algorithmic ways of achieving consensus.
Consenter set
The ordering service nodes actively participating in the ordering process on a channel. These nodes are also known as
"consenters."
Console
The name of the user interface in the IBM Blockchain Platform. The console allows users to view, create, and manage their
deployments. Because the public and private keys are only stored locally in the browser the console runs on, users maintain
total control over their keys.
Consortium
The group of non-orderer organizations listed on the orderer system channel.The following lines do not apply to orderers that do
not use a system channel: These are the only organizations that can create channels. At channel creation time, all organizations
added to the channel must be part of a consortium. However, an organization that is not defined in a consortium may be added
to an existing channel. While a blockchain network can have multiple consortia, most blockchain networks have a single
consortium.
CouchDB
A document store that can be used as the state database of your peers. Using CouchDB allows you to use rich queries and
deploy indexes with your smart contract.
Current state
The current state of the ledger represents the latest values for all keys that are ever included in its chain transaction log. Because
current state represents all latest key values known to the channel, it is sometimes referred to as the world state. Smart
contracts execute transaction proposals against current state data. The current state changes every time when the value of a key
changes or a new key is added and is critical to a transaction flow because the latest key-value pair must be known before it can
be changed. Peers commit the latest values to the current state of the ledger for each valid transaction in a block. The current
state is stored the state database associated with a peer.
Dynamic membership
A member can be dynamically added to the network by a user withregistrar privilege. Members are also assigned roles and
attributes, which control their access and authority on the network. Neither roles nor attributes can be assigned dynamically

though. Hyperledger Fabric supports the addition or removal of members, peers, and ordering service nodes, without
compromising the operations of the overall network. Dynamic membership is critical when business relationships adjust and
entities need to be added or removed for various reasons.
Endorsement
The process by which transactions are validated. Endorsement rules are implemented by specifying endorsement policies,
which define the organizations that must approve of a transaction.
Endorsement policy
Defines the peer nodes on a channel that must execute transactions that are attached to a specific application, and the required
combination of responses (endorsements). A policy could require that a transaction be endorsed by a minimum number of
endorsing peers, a minimum percentage of endorsing peers, or by all endorsing peers that are assigned to a specific application.
Policies can be curated based on the application and the desired level of resilience against misbehavior, whether deliberate or
not, by the endorsing peers. A submitted transaction must satisfy the endorsement policy before it is marked as valid by
committing peers. A distinct endorsement policy to deploy transactions is also required.
Genesis block
The configuration block that initializes a blockchain network or channel, and also serves as the first block on a chain.
Gossip
Hyperledger Fabric allows peers to gather important network information from each other without having to rely on the ordering
service. The gossip data dissemination protocol provides a secure, reliable, and scalable way for peers to exchange messages
between each other. For example, if peers miss some blocks because of delays, network outages, or other reasons, they can
sync up to the current ledger state by using gossip messaging to contact other peers in possession of these missing blocks.
HSM
Hardware Security Module. Provides on-demand encryption, key management, and key storage as a managed service. HSM is a
physical appliance that handles the resource-intensive tasks of cryptography processing and reduce latency to applications. For
more information, see Hardware Security Module.
Hyperledger Fabric
Hyperledger Fabric is a business blockchain framework that the Linux Foundation hosts to serve as a foundation for developing
blockchain applications or solutions with a modular architecture. Hyperledger Fabric components such as consensus and
membership services are plug-and-play.
Install
The process of placing a smart contract on a peer’s file system. You must install the smart contract on every peer that wants to
access or change the data governed under the smart contract.
Instantiate
The process of starting and initializing a smart contract container on a channel with peers running Fabric v1.4.x and v1.4
capabilities. After a smart contract is installed on the peers and every peer has joined the channel, the smart contract must be
instantiated on the channel. Instantiation performs any necessary initialization of the smart contract, which includes setting the
key value pairs that comprise a smart contract's initial world state. After instantiation, peers that have the smart contract

installed can interact with the data governed by the smart contract. Starting in Fabric v2.x, the instantiation process has been
replaced with a propose, approve, and commit model.
Kafka
A consensus plug-in implementation for Hyperledger Fabric that results in a cluster of ordering service nodes in the blockchain
network. Kafka implementations and Raft implementations are intended for production networks. However, only Raft ordering
service clusters are natively supported and can be created using the IBM Blockchain Platform.
Ledger
Comprised of a literal "chain of blocks" that store the immutable, sequenced record of transactions, as well as a state database
to maintain current state. There is one ledger per channel, and updates to it are managed by the consensus process according to
the policies of a particular channel.
LevelDB
A key-value store that can be used as an option for the state database for your peers. LevelDB stores the current state as key-
value pairs, and does not support the use of indexes or rich queries.
Lifecycle endorsement policy

On a channel, the lifecycle endorsement policy specifies which organizations can approve a smart contract definition and how
many of them are required to approve the definition or update. The default lifecycle endorsement policy requires a majority of all
organizations on the channel to approve.
Member
Also known as "organizations", members in a blockchain network, similar to the members of any group, form the structure of the
network. A member can be as large as a multi-national corporation or as small as an individual. Members are enrolled into the
network with a certificate that grants them permissions to use the network as either a service provider (for example, issuing
certificates, validating/ordering transactions) or as a consumer. The former provides foundational blockchain services that
include transaction validation, transaction ordering, and certificate management services. Consumer members use the network
to invoke transactions against the distributed ledger. Members can have multiple Peers.
MSP
An abbreviation of Membership Service Provider, which provides the definition of an organization, including the root certificate
of the CA issuing certificates for the entities associated with that organization, as well as the sign cert of the admin of that
organization. MSPs also exist at the local level of a peer or ordering node, and are the authentication mechanism that verifies the
admin users of the node. In the IBM Blockchain Platform, MSPs can be exported from one console into another, allowing users
to create an organization in one console, import it to another console, and operate it (for example, to create a channel). MSPs
can also be imported into an ordering service, forming a "consortium", the list of organizations allowed to create and join
channels.
Network
An instance of an IBM Blockchain Platform service on IBM Cloud.
Node
The communication entity of the blockchain. There are three types of nodes: CA, peer, and ordering node.

Ordering node
The node that collects transactions from network members, orders the transactions and bundles them into blocks. Also known
as orderer. These blocks are then distributed to peers, which then verify the blocks and add them to the ledgers on each
channel. Ordering nodes contain the cryptographic identity material that is tied to each member and authenticate the identity of
clients and peers to access the network. The overall function that an ordering node or collection of nodes provides is known as
the ordering service.
Organization
See Member.
Out of band
An expression used to refer to sharing network artifacts outside of the console UI, for example by email or some other file
transfer mechanism. After submitting a smart contract proposal, the originator can share the smart contract package and
package id with other channel members in an out of band operation by emailing this information to them.
Peer
A blockchain network resource that provides the services to execute and validate transactions, and maintain ledgers. The peer
runs smart contract and is the holder of transaction history and the current state of assets on ledgers. They are owned and
managed by organizations and are joined to channels.
Propose
Referring to a step in the Hyperledger Fabric v2.x smart contract lifecycle, a smart contract definition is proposed to a channel
for approval by the organizations that are specified in the channel lifecycle endorsement policy. A smart contract proposal
contains a smart contract definition name, version, package, endorsement policy, and optionally a private data collection.
Quorum
In a Raft ordering service, a quorum represents the number of nodes that must be available for transactions to be processed.
This number is a majority of the total number of nodes in the consenter set of the channel. In other words, if you have one node,
you need that node available to have a quorum, because the majority of one is one. Similarly, if you have two nodes, you will
need both available, since the majority of two is two (for this reason, a configuration of two nodes is discouraged; there is no
advantage to a two node configuration). In a similar vein, the majority of three is two, the majority of four is three, the majority of
five is three, and so on.
Raft
Raft is a crash fault tolerant (CFT) ordering service based on an implementation of Raft protocol in etcd . Raft follows a “leader
and follower” model, where a leader node is elected (per channel) and its decisions are replicated by the followers. Raft ordering
services should be easier to set up and manage than Kafka-based ordering services and a cluster of these nodes can be created
using the IBM Blockchain Platform.
SDK
Hyperledger Fabric Client Software Development Kits (SDKs) enable interaction between your client application and your
blockchain network. Fabric supports three SDKs: Go, Node, and Java) that include documentation for the available APIs.
Service credentials

Service credentials are in JSON format and contain the API endpoint information and enrollIDs/secrets for your network
resources, that is, CAs, ordering nodes, and peers. Your application interacts with network resources through these API
endpoints.
Service discovery
Fabric service discovery allows your client applications to dynamically find the peer and ordering endpoints of your network. If
you do not configure service discovery in your application, the endpoint information of peer and ordering nodes on your channel
needs to be added manually to your connection profile or your application.
Shim
When referring to smart contracts or chaincode, the shim represents a set of Hyperledger Fabric chaincode APIs that a smart
contract can use to access state variables, transaction context, and call other smart contracts.
SignCert
The certificate that any entities, whether organizations or admins, attach to their proposals or proposal responses. These
signCerts are unique to an entity and are checked by the ordering service to make sure they match the signCert on file for that
entity.
Smart contracts
See Chaincode.
Smart contract definition

Used by the Hyperledger Fabric v2.x smart contract lifecycle, the smart contract definition contains the elements that members
of an organization agree to before a smart contract can be committed to a channel. The definition is composed of a smart
contract definition name, version, endorsement policy, and private data collection. Changes to the version, endorsement policy,
and private data collection must be approved by the organizations that are specified in the channel lifecycle endorsement policy
before the updated version can become active on the channel.

See Endorsement policy.
Smart contract package

Used by the Hyperledger Fabric v2.x smart contract lifecycle, the smart contract package contains the business logic that reads
from or writes to the smart contract ledger. The package is attached to a smart contract definition proposal. Smart contract
packages can only be installed on peers that are running a Fabric v2.x or higher image.
State database
Current state data is stored in a database on the peers for efficient reads and queries from smart contracts. You can select to
use either LevelDB or CouchDB as the state database of your peers.
Transaction
Changes to the ledger are achieved by invoking "transactions", which either involve assets or changes to the configuration of a
channel. "Asset" transactions usually involve a smart contract governing the rules of a transaction between counter-parties,
while the rules governing configuration transactions are established in the configuration of the channel itself.

User
A user is a participant in a blockchain network that has indirect access to the ledger through a trust relationship with a Certificate
Authority.
World state
See Current state.

Release notes
Use these release notes to learn about the latest changes to IBM® Blockchain Platform for IBM Cloud built on Hyperledger Fabric
v1.4.12, v2.2.10, and v2.4.8.
Installing patches provides instructions on how to apply patches to your existing blockchain nodes. Patches are cumulative, so
select the latest available patch to include all earlier patches.
28 Feb 2023
Certificate Authority (CA) patch 1.5.5-9, Peer and ordering node patch 1.4.12-23, 2.2.10-1, 2.4.8-1.
Miscellaneous bug fixes and security patches.
Severity: medium
31 Jan 2023
Severity: medium
04 Jan 2023
Known issue: If the Launch the IBM Blockchain Platform console button is not enabled, refresh the page to enable it.
Severity: medium
07 Dec 2022
Updates to VS Code documentation.
Severity: medium
08 Nov 2022
Severity: medium
11 Oct 2022

Severity: medium
13 Sept 2022
Severity: medium
16 Aug 2022
Added ability to remove the system channel and ability to create orderers without a system channel.
Added support to use the channel participation APIs offered by Fabric peers/orderers to manage channels.
Severity: medium
19 July 2022
Severity: medium
22 June 2022
Severity: medium
01 June 2022
Severity: medium
03 May 2022
v2.5.3 release updates listed in What's new for May 03, 2022.
Severity: medium

05 Apr 2022
Certificate Authority (CA) patch 1.5.2-8, Peer and ordering node patch 1.4.12-11, 2.2.5-3.
Severity: medium
08 Mar 2022
Severity: medium
08 Feb 2022
Severity: medium
11 Jan 2022
14 Dec 2021
16 Nov 2021
Deprecation notice for IBM Blockchain Platform for IBM Cloud: Because Kubernetes v1.22 deprecates a number of APIs,
nodes running Kubernetes v1.13, v1.14, or v1.15 will no longer be updated to the latest IBM Blockchain Platform for IBM Cloud
patches. In addition, no Kubernetes cluster nodes will be updated if the master node is not reachable. Impacted clusters are
identified via Kubernetes calls to the master node and calls to health check endpoints for blockchain components. Migration
instructions for impacted clusters will be posted here soon.
26 Oct 2021
05 Oct 2021

10 Aug 2021
13 Jul 2021
Certificate Authority (CA) patch 1.5.0-1, Peer and ordering node patch 1.4.12-2, 2.2.3-2
16 Jun 2021
The platform has been updated to include support for Hyperledger Fabric v1.4.12 and v2.2.3.
05 May 2021
13 Apr 2021
22 Feb 2021
Certificate Authority (CA) patch 1.4.9-5, Peer and ordering node patch 1.4.9-5 and 2.2.1-5
12 Jan 2021
New logging configuration panel

A new panel is available to override peer and ordering node log levels for specific component loggers. See Configuring node
logging for more information.
08 Dec 2020
19 Nov 2020

When you link a new IBM Blockchain Platform service instance to a Kubernetes cluster that uses community Kubernetes
Ingress, the cluster Automatic Load Balancer (ALB) pods need to be restarted which can take five to ten minutes. If the restarts
have not completed before you create your first blockchain Certificate Authority (CA), peer, or ordering node, the initial green
status indicator on the new node can take slightly longer than you are accustomed to while the pods restart. Existing blockchain
service instances are not impacted.
02 Nov 2020
Important: If you are running OpenShift Container Platform 3.11 in IBM Cloud, it is recommended that you upgrade
your cluster to 4.4 now in order to fully take advantage of the new features. After you upgrade your cluster, follow
instructions to refresh your blockchain console to experience the latest functionality in this release.
Fabric v2.x node upgrade

In addition to deploying new nodes based on the latest Fabric v2.2.1 image, you can upgrade your existing nodes to Fabric v2.x
and the capabilities of your channels, allowing organizations to take advantage of the new smart contract lifecycle process.
For information about upgrading nodes, check out Upgrading to a new version of Fabric. For information about updating the
capabilities of your channels, check out Capabilities.
Support for Fabric v2.x smart contract lifecycle

The platform has been updated to include support for Fabric v2.x smart contract lifecycle process, which enables the distributed
governance of smart contracts. Learn mode about how to Deploy a smart contract using Fabric v2.x.
Improvements for HSM support

A new process is available to configure an HSM for your blockchain nodes, delivering faster performance.
Certificate renewal enhancements

Customers can now use the console to renew certificates that have expired or are about to expire, including the Certificate
Authority (CA) TLS certificate, peer and ordering node enrollment certificates, and peer and ordering node TLS certificates.
Remove registered user from CA

You can now delete registered users from a CA.
1 Oct 2020
CA, Peer, and ordering node patch 1.4.7-3, 2.1.1-3
25 Aug 2020

Certificate expiration dates have been added throughout the component details, making it easier to monitor and track certificate
expiration dates. See Certificate Management to learn more about your responsibilities. In addition, it is now possible to enable
Node OU support for your MSPs and channels through the console. Read more about Node OU support, why this is important,
and how to simplify certificate renewal for the MSPs on your network.
14 July 2020
18 June 2020
Peer and ordering node patch 1.4.7-0
IBM considers this a critical patch that you should apply at your nearest opportunity.Not applying this patch risks being
susceptible to a data integrity issue if you experience a CouchDB or underlying storage crash on your peer. This patch updates
the CouchDB delayed_commits configuration property to false. The prior setting could cause the peer's CouchDB database to
be in an inconsistent state in the event of a CouchDB or underlying storage system crash. The new setting ensures that a peer
will recover from crashes in a consistent state. As always, it is recommended to utilize an endorsement policy that requires
multiple peers to endorse a transaction, to avoid an inconsistency from a single peer from impacting the overall blockchain
network state.
To be certain that your peers have no database corruption, you should reprovision your peers.
Important: Miscellaneous bug fixes and security patches. If you are running OpenShift Container Platform 3.11 in IBM
Cloud, it is recommended that you upgrade your cluster to 4.3 now in order to fully take advantage of the new features.
After you upgrade your cluster, follow instructions to refresh your blockchain console to experience the latest
functionality in this release.
Fabric peer and ordering node images

The platform introduces the capability to deploy new peer and ordering nodes based on either Hyperledger Fabric v1.4 or v2.x.
Deploying peer and ordering nodes with the latest Fabric images is recommended to ensure that you have access to current
Fabric fixes and features. It is not currently possible to migrate existing nodes to Fabric v2 images.
Elimination of Docker daemon dependency

Leveraging the Fabric v2 external chaincode launcher capability, when you deploy a peer based on the Fabric v2.1.1 image,
smart contracts are deployed into their own pod rather than inside a container on the peer pod.
If your Kubernetes cluster is configured to use multizone-capable storage, new peer and ordering nodes can be deployed that
leverage multizone storage, effectively extending their high availability across cluster zones. See Multizone-capable Storage for
more information.
Kubernetes version upgrade

IBM Blockchain Platform requires Kubernetes v1.15 - v1.18. If your existing Kubernetes cluster is running v1.14 or lower, you

need to upgrade your cluster before you can update your existing blockchain components to this latest release.
20 May 2020
CA, peer, and ordering node patch 1.4.6-2
Support for Intermediate Certificate Authorities (CAs)

You now have the option to configure an intermediate CA using the console or APIs to override the default CA settings. See the
tutorial on Creating an intermediate Certificate Authority to learn more.
Updated connection profile

The generated connection profile that client applications use to connect to the network has been streamlined and is now
downloadable from the Organizations tab. See Downloading a connection profile to learn how.
16 April 2020
CA, peer, and ordering node patch 1.4.6-1
Support for AWS HSM

If you plan to use AWS HSM, you must include the immutable and AltId parameters in your BCCSP configuration. See Fabric
documentation for details.
Miscellaneous bug fixes
24 March 2020
Note: IBM is in the process of migrating existing IBM Blockchain Platform consoles to v2.1.3, therefore, the new features
described in this list may not yet be available in your console. Unsure what version you are currently using? Click the
question mark icon in the upper right corner of the console. The IBM Blockchain Platform version is visible under the page
heading. Existing customers will receive a Cloud notification with more details about when their console will be migrated.
Hyperledger Fabric v1.4.6
All new nodes are deployed using Hyperledger Fabric v1.4.6. If you have an existing blockchain network, you should review the
topic on Capabilities to understand how this new Fabric version can impact your network.
Hardware Security Module (HSM) support for node identities
Full cryptographic HSM support is now available for HSMs that implement the PKCS #11 standard. Using an HSM provides on-
demand encryption, key management, and key storage. When you deploy a CA, peer, or ordering node, you now have the option
to store the private key for the node identity in an HSM. See Configuring a node to use a HSM for more details.
Support for adding and removing ordering nodes from an existing ordering service
Previously, an ordering service could only contain one or five ordering nodes and they all were contributed from the same
organization. Now, the ordering service can be deployed across multiple organizations in a blockchain network, enabling
individual organizations to add and remove individual ordering nodes as required. Multi-organizational transaction ordering
improves the decentralized nature of a blockchain network. Learn more about the process in the new Adding and removing Raft

ordering service nodes tutorial.
Ability to override default CA, peer, ordering node configuration
Hyperledger Fabric includes many configuration options for a CA, peer, or ordering node. A subset of those options for the CA,
peer and ordering node can now be overridden by using the console or the APIs.
Full Java smart contract development support
In addition to smart contracts written in JavaScript, TypeScript, and Go programming languages, it is now possible to deploy
Java smart contracts from the console. Moreover, Java can be freely mixed and matched with other application and smart
contract programming languages, including JavaScript, TypeScript, and Go. This heterogeneous programming language support
enables an organization to capitalize on the full range of its development skills.
In order to use Java chaincode, developers should be aware that:
Java 11 is required to execute Java smart contracts.

Gradle v4.x and Maven v3.x are used to build Java smart contracts.
Custom Gradle versions can be used by using a Gradle wrapper.
Java smart contracts require the fabric-chaincode-shim at v1.4.6 or later, as this version is the first version that includes
support for Java 11.
For an example of a Java smart contract, see the FabCar Java smart contract from Fabric v1.4.
v2 APIs available
New IBM Blockchain Platform console APIs using the route /v2/ are now available. Use of the earlier /v1/ APIs continues to
be supported. See IBM Blockchain Platform APIs for more information.
High Availability Certificate Authority
When a CA is deployed, replica sets can be configured to ensure High Availability of the node. Note that CA replica sets require a
PostgreSQL database. Learn more in the Building a high availability Certificate Authority (CA) tutorial.
6 February 2020
Update default resource allocation
The default memory allocation for the peer container has been increased from 0.4GB to 1GB. When deploying a new peer, the
peer container will now default to 1GB memory, but you can adjust this value according to your use case. Increasing the memory
alleviates some resource contention that could occur during smart contract instantiation.
Existing peer containers are not impacted.
Peer and ordering node patch 1.4.3-1
The Ingress timeout for the gRPC web proxy has been increased to avoid an error during smart contract instantiation. It is
recommended that you apply this patch to your existing peer and ordering nodes.
11 December 2019
15 November 2019
Service availability in two new regions

The IBM Blockchain Platform for IBM Cloud is now available to be provisioned in two new IBM Cloud regions:US East, and AP
South. Refer to the locations information to see the data centers that are available in those regions.
06 November 2019
Simplified component creation flows
Peer, CA and ordering service creation has been streamlined. Now, when you create a node, you have to select a checkbox to
configure advanced deployment options.
02 October 2019
Peer, CA, and ordering node patch 1.4.3-0
Zone selection for ordering nodes
When multiple zones are configured in your Kubernetes cluster, you can now choose which zone to deploy your ordering node
to. Spreading nodes across zones is useful for ensuring high availability of your blockchain network.
Ability to set peer to be an anchor peer when the peer joins the channel
Users can now choose to designate a peer to be an anchor peer when the peer is being joined to the channel, rather than after
the peer has joined the channel. An anchor peer must exist for each organization in order for cross organizational gossip to work.
Anchor peers are also required for private data and service discovery to work. Learn how.
Ability to add a peer to a channel from the Channels tab
A peer can now be joined to a channel directly from the Channels tab. See Join a peer to a channel for more details.
Export/Import all
Allows for the bulk export and import of your blockchain network, including nodes, MSPs and identities, rather than having to
export and import these components one at a time. See the topic on Exporting and importing in bulk for more details.
Hyperledger Fabric v1.4.3
All new nodes are deployed using Hyperledger Fabric v1.4.3. If you have an existing blockchain network, you should review the
topic on Capabilities to understand how this new Fabric version can impact your network.
21 August 2019
Peer node patch 1.4.1-3
With this patch, you now have the ability to upload additional admin identities for a peer. See Adding new peer admin
certificates for more information.
Select peer zone (IBM Blockchain Platform for IBM Cloud only)
If multiple zones are configured in your Kubernetes cluster on IBM Cloud, you can now use the console UI to select the zone
where the peer is deployed. This capability is important if you are configuring multizone HA for peers.
Peer database support now includes LevelDB
You now have the option to choose between CouchDB and LevelDB for your Peer database. For more information, see LevelDB
vs CouchDB.
Certificate Authority (CA) updates

The console UI no longer stores the admin enroll id and secret that you provide when you create a CA. Therefore, after you
create a CA, you are responsible for generating the admin certificates by using the new Associate identity and passing in the
enroll id and secret. This change improves CA security. See Associating the identity of the CA admin for more details.
12 August 2019
Beta trial of the IBM Blockchain Platform ends
The Beta trial of the IBM Blockchain Platform, which began on February 12, 2019, has officially ended. All of the beta instances
of your console and the components that you deployed into your Kubernetes cluster using the beta console will be deleted.
Peer node patch 1.4.1-2
This patch contains a security fix for the peer couchDB container.
10 July 2019
Ordering node patch 1.4.1-2
This patch fixes a problem that occurs when ordering nodes restart. The genesis block is updated which prevents the ordering
node from communicating with the other nodes in the ordering service. You can apply this patch to all existing ordering nodes in
your ordering services by following these instructions to update each ordering node. All new ordering nodes that you create will
automatically include this fix.
Anchor peer removal
You now have the ability to remove anchor peers from a channel.
Bug fixes and translation updates.
24 May 2019
Raft consensus protocol
The five node Raft ordering service, recommended for production networks, is now available. In addition, for development and
testing purposes, you can deploy a single node Raft ordering service.
9 May 2019
Introducing IBM Blockchain Platform Console APIs
APIs are now available to provision, edit, and delete peer, orderer, and CA nodes, making it possible to script the building of your
blockchain network. Use the documentation in the IBM Cloud API documentation repository to learn more about the APIs and
try them out. In addition, see the topic on Building a network with APIs for instructions on how to use the APIs to build out your
network.
Channel governance
Channel governance updates allow policies to be reconfigured. You can also control which channel members need to sign a
channel update and you can orchestrate signature collection.
17 April 2019

Ability to size and scale node resources
When you deploy a node you now have the ability to specify the amount of CPU, memory, and storage to your containers, where
applicable. You can later scale their resources up or down at a later time according to usage patterns. For more information, see
Allocating resources.
Use of IBM Cloud Identity and Access Management (IAM)
IAM is used to control user access to the console UI as well as restricting the actions they can perform in the UI. See this topic
for information on how to add and remove users from the console.
3 April 2019
Support for external CA
When you add a peer or orderer node, you have the option to use certificates from an external CA, one that is not hosted by IBM.
See this topic on Using certificates from an external CA with your peer or ordering nodefor more information.
Tuning orderer performance
New orderer tuning parameters are available in the console to give you more control over your orderer throughput and
performance. See this topic on Tuning your orderer for instructions on how to configure the parameters.

Known issues
This page describes known issues that you might encounter when you use IBM Blockchain Platform for IBM Cloud.

Troubleshooting
General problems can occur when you use the console to manage nodes, channels, or smart contracts. In many cases, you can
recover from these problems by following a few simple steps.
This topic describes common issues that can occur when you use the IBM Blockchain Platform console.
Issues with the Console
Why is my IBM Blockchain Platform user interface unable to connect to cluster after deployment? (Ingress issue)
Why are my console actions failing in my Chrome browser Version 77.0.3865.90 (Official Build) (64-bit)?
When I hover over my node, the status is Status unavailable , what does this mean?
When I hover over my node, the status is Status undetectable , what does this mean?
Why am I getting the error Unable to get system channel when I open my ordering service?
Why did my smart contract installation, instantiation or upgrade fail?
Why is my smart contract fail to install with an error on my peer?
Why is my Node.js smart contract fail to endorse?
Why is the smart contract that I installed on the peer not listed in the UI?
My channel, smart contracts, and identities have disappeared from the console. How can I get them back?
Why am I getting the error Unable to authenticate with the enroll ID and secret you provided when I create
a new organization MSP definition?
Why am I getting the error An error occurred when updating channel when I try to add an organization to my
channel?
When I log in to my console, why am I getting a 401 unauthorized error?
Why am I getting a Cluster linking is taking too long error when I try to link my Kubernetes cluster in IBM Cloud
to my IBM Blockchain Platform service instance?
Why am I getting an error “all SubConns are in TransientFailure” on the console?
Issues with your Nodes
Why is my first start of a smart contract returns the following error: no suitable peers available to initialize from?
Why are my node operations fail to operate after I create my peer or ordering service?
Why does my peer or ordering node fail to start?
Why does my blockchain node fail to restart?
What is the proper way to clean up a failed node deployment?
How can I view my smart contract container logs?
Why is my CA, peer, or ordering node that is configured to use HSM not working?
Why are my transactions returning an endorsement policy error: signature set did not satisfy policy?
Why are the transactions I submit from VS Code failing with a No endorsement plan available error?
Why are the transactions I submit from VS Code failing with an endorsement failure?
Why is my peer unable to communicate with my ordering node?
When I hover over my node, the status is red, what does this mean?
How do I disable the network policies in my namespace?
How do I delete a peer pod?
How can I recover a contract after a failed upgrade of the smart contract container?
Issues on IBM Cloud
My Kubernetes cluster on IBM Cloud expired. What does this mean?

After I deploy a node, I'm seeing a message in my Kubernetes cluster on IBM Cloud reporting that the pod has unbound
immediate persistent volume claims. Is this an error?
After I deploy a node, I'm seeing a message in my Kubernetes cluster on IBM Cloud reporting that the pod has hit a crash
loop backoff. Is this an error?

Why is my IBM Blockchain Platform user interface unable to connect to cluster after
deployment (Ingress issue)?
What’s happening
When deploying a new IBM Cloud Kubernetes Service cluster and a new IBM Blockchain Platform environment, the IBM
Blockchain Platform user interface is unable to connect to the provision components. The component status does not turn green
even when the pod shows it is running fine from the IBM Cloud Kubernetes Service user interface or the command line interface
(CLI).
You may also see errors connecting to the proxy URL such as the following reported by the IBM Blockchain Platform console:
"stitch_msg": "unable to get block: grpc web proxy's message: "Response closed without headers". This
can happen when encountering CORS or untrusted TLS issues with the grpc web proxy.",
Why it’s happening

This problem can occur when the cluster is created after 01 December 2020 with version 1.18 or higher. Or, after you finish
deploying the IBM Blockchain Platform while the Kubernetes user interface or CLI still displays the pod as running, but the
orderer or the peer user interface does not appear online.
Before resolving this problem, you can check the application load balancer (ALB) replica set by running kubectl get
replicasets -n kube-system and look for result similar to public-crbpt86avw0kfob73dpb3g-alb1-875bc4d57 2 2 2
24h .
For clusters created after 01 December 2020 with version 1.18 or higher, you can check that the ingress configuration as
follows:
1. Run kubectl get ingress --all-namespaces to find out which are the ingress matching nodes that are having issues.
2. Run kubectl get ingress <componentname> -n <namespace> -o yaml to clear the current ingress configuration.
3. Verify if the following configuration is missing:
annotations:
nginx.ingress.kubernetes.io/backend-protocol: HTTPS
nginx.ingress.kubernetes.io/proxy-ssl-verify: "false"
How to fix it
To resolve this problem, you can execute the following steps:
Get the list of ALB replica set. If your cluster has only one ALB, you can get the replica set as follows:
kubectl get replicaset -n kube-system | grep <ALB-name>
If you have multiple ALBs, execute the following steps for each ALB as follows:
1. Get the list of all replica sets.
kubectl get replicaset -n kube-system | grep alb
For example, you will see multiple replica sets listed as follows:
$ kubectl get rs -n kube-system | grep alb

NAME DESIRED CURRENT READY AGE
public-x-alb1-59db7dbfb4 2 0 0 6d4h
public-x-alb1-6486c45c96 2 2 0 3d17h
public-x-alb1-d856b94c4 0 0 0 17d
2. Delete all the replica sets except for the latest one.
kubectl delete replicaset -n kube-system <replicaset-name>
Based on the example shown, you need to delete the extra replica sets as follows:
kubectl delete replicaset -n kube-system public-x-alb1-59db7dbfb4

kubectl delete replicaset -n kube-system public-x-alb1-d856b94c4
3. Get the list of replica set again to ensure that there is only one remaining.
kubectl get replicaset -n kube-system | grep <ALB-name>
Referring to the example, the result will display as follows:
public-x-alb1-6486c45c96 2 2 2 3d17h
Why are my console actions failing in my Chrome browser Version 77.0.3865.90

(Official Build) (64-bit)?
What’s happening
The console has been working successfully, but requests have started to fail. For example, after I create an ordering service and
open it I see the error: Unable to get system channel. If you associated an identity without administrative
privilege on the ordering service node, you will not be able to view or manage ordering service
details.

This problem can be caused by a bug introduced by the Chrome browser Version 77.0.3865.90 (Official Build) (64-
bit) that causes actions from the browser to fail.
How to fix it
To resolve this problem, open the console in a new browser tab in Chrome. Any identities that you saved in your console wallet
will persist in the new browser tab. To avoid this problem you can upgrade your Chrome browser version. Ensure you have
downloaded all of your wallet identities to your local machine before closing your browser.
When I hover over my node, the status is Status unavailable or Status unknown , what does
this mean?
What’s happening
A CA, peer, or ordering node has a gray status box, meaning the status of the node is not available. Ideally, when you hover over
any node, the node status should be Running .

This problem can occur if the node is newly created and the deployment process has not completed. If the node is a CA and the

status has been gray for more than a few minutes, then it is likely that the deployment process has failed. Peers and ordering
nodes take longer to deploy, but this condition can also occur when the health checker that runs against the peer or ordering
nodes cannot contact the node. The request for status can fail with a timeout error because the node did not respond within a
specific time period, the node could be down, or network connectivity is down.
How to fix it
If this is a new node, wait a few more minutes for the deployment to complete. You can try reloading the page in your browser to
refresh the status. If the node is not new, examine the associated node logs for errors to determine the cause.
What’s happening
The node status in the tile for the peer or ordering node is yellow, meaning the status of the node cannot be detected. Ideally,
when you hover over any node, the node status should be Running .

This condition can occur on peer and ordering nodes that wereimported to the console and the health checker cannot run
against the node. This status happens because an operations_url was not specified when the node was imported. An
operations URL is required for the node health checker to run. The node itself is likely Running , but because the operations URL
was not specified, its status cannot be determined. This problem can also occur if you migrated your IBM Cloud Kubernetes
cluster Ingress from IBM Cloud Kubernetes Service Ingress to the community Kubernetes Ingress image, or vis versa.
How to fix it
If you imported the node:
You can resolve this problem by performing the following steps:
1. Click the node tile to open it.

2. Click the Settings icon.
3. Click Associate identity, view and make note of the identity that is associated with this node. ClickCancel to close this
panel.
4. Click Export to generate a JSON file for the node.
5. Edit the generated JSON file and enter the operations_url for the node. The value of the operations_url depends on
how it was configured as well as various network settings. This value needs to be provided by the network administrator
who deployed the node.
6. Click Delete. This step removes the imported node from the console, but does not delete the actual node.
7. From the Nodes tab, click Add Peer or Add ordering service followed by Import an existing peer or Import an existing
Ordering service.
8. Click Upload JSON and browse to the JSON file you just edited. Click Next.
9. Associate the same identity you noted in step three.
10. Click Add peer or Add ordering service. The health checker can now run against the node and report the status of the
node.
If you migrated your cluster Ingress: You need to refresh your blockchain console.
What’s happening
After you create an ordering service, the status is Running . But when you open the ordering service you see the error:

Unable to get system channel. If you associated an identity without administrative privilege on the
ordering service node,
you will not be able to view or manage ordering service details.

This problem can occur when the console has lost contact with your Kubernetes cluster on IBM Cloud. This can happen if your
console has not recently communicated with your cluster, or if you have made changes to your cluster that have overridden the
settings used by the IBM Blockchain platform.
How to fix it
You can renew the communication between your console and the IBM Kubernetes service cluster on IBM Cloud by clicking on
the service instance of your console in your Resource list and clicking the Refresh cluster button. When the link between your
cluster and your console has been refreshed, click the Launch the IBM Blockchain Platform button.
What’s happening
It is possible you may experience an error when installing, instantiating or upgrading a smart contract. For example, when you
try to install a smart contract on a peer, it fails with the error An error occurred when installing smart contract on
peer.

You may receive this error if this version of the smart contract already exists on the peer, or if your peer is out of resources.
Open your Kubernetes dashboard and ensure the peer status is Running.
Open the peer node and ensure the smart contract version does not already exist on the peer and try again with the
proper version.
If you are still experiencing problems after the node is up, check your node logs for errors.
What’s happening
Installing a smart contract on a peer fails with an error similar to the following:
An error occurred when installing smart contract on peer.

error in simulation: failed to execute transaction
421fac...2fda: error sending: timeout expired while executing transaction.

When running the IBM Blockchain Platform on s390x architecture, or in an environment with constrained resources, it is
possible that smart contract installation can fail on a peer if the default timeout is too short on the peer that is running the Fabric
v2x image.
How to fix it
In some cases, if you simply wait several minutes and then refresh theSmart contracts tab in the console, you can see that the
smart contract was successfully installed. You can customize how long the console waits for the installation to complete by
changing the console settings with the APIs. See the fabric_lc_install_cc_timeout_ms setting. In some cases, it is the

peer itself that is timing out and you need to override the peer configuration to extend its time out.
1. From the console, open the peer tile and click theSettings icon.
2. Click Edit configuration JSON (Advanced).
3. In the Configuration updates box paste the following text and clickUpdate peer.
{
"chaincode":{
"startuptimeout":"300s",
"installTimeout":"600s",
"executetimeout":"30s"
}
}
The peer restarts and then you can retry the smart contract installation. Because the original installation failed you need to
specify a new smart contract name and version.
What’s happening
My Node.js smart contract endorsement fails with the error:
Error: endorsement failure during query. response: status:500 message:"error in simulation: failed to
execute transaction 6cbcf9f94bdef3fc68abba5604e46293ae: could not launch chaincode nodecc:1.1: error
building chaincode: error building image: external builder failed: external builder failed to build:
external builder 'ibp-builder' failed: exit status 3"

By default, a Fabric v1.4 peer creates a Node v8 runtime, and a Fabric v2.x peer creates a Node v12 runtime. In order for the
smart contract to work with Node 12 runtime, the fabric-contract-api and fabric-shim node modules must be at v1.4.5
or greater.
How to fix it
If you are using a smart contract that was originally written to work with Fabric 1.4, update the Node modules by running the
following command before deploying the smart contract on a Fabric v2.x peer. See Support and compatibility for fabric-
chaincode-node for more information.
What’s happening
A smart contract was installed on a peer but when you click on theSmart contracts tab, it is not listed.

This issue can occur when another user or application installs the smart contract onto the peer and you do not have the peer
admin identity in your browser wallet.
How to fix it

In order to view the smart contracts installed on a peer, you need to be a peer admin. Ensure that the peer admin identity exists
in your browser wallet. If it does not, you need to import it into your console wallet.
My nodes, channels, smart contracts, and identities have disappeared from the
console. How can I get them back?
What’s happening
Nodes, identities, channels, or smart contracts (or some combination of these) that I successfully deployed into the console are
no longer available.

One of the features of IBM Blockchain Platform is that you are now responsible for securing and managing your certificates.
Therefore, they are only persisted in the browser local storage to allow you to manage the component. If you are using a private
browser window and then switch to another browser or non-private browser window, the identities that you created will be gone
from your wallet in the new browser session. Therefore, it is required that you export the identities from the wallet in your private
browser session to your file system. You can then import them into your non-private browser session if they are needed.
Otherwise, there is no way to recover them.
Whenever you create a new organization MSP definition, you generate keys for an identity that is allowed to administer the
organization. Therefore, during that process you must click the Generate and then Export buttons to store the generated
identity in your wallet and then save it to your file system as a JSON file.
To resolve this problem in your browser, you need to import those identities and associate them with the corresponding
node:
In the browser where you are experiencing the problem, click the Wallet tab followed by Add identity to import the
JSON file into your wallet.
Click Upload JSON and browse to the JSON file you exported using the Add files button.
Click Submit.
Now open the peer or ordering service node that this identity was originally associated to, and click on theSettings
icon.
Click the Associate identity button.
Select the identity you just imported to your console wallet from the drop-down list.
Click Associate.
Repeat this process for each identity that was in the wallet of the original browser.

This problem can also occur when the console has lost contact with your Kubernetes cluster on IBM Cloud. This can happen if
your console has not recently communicated with your cluster, or if you have made changes to your cluster that have overridden
the settings used by the IBM Blockchain platform.
How to fix it
You can renew the communication between your console and the IBM Kubernetes service cluster on IBM Cloud by clicking on
the service instance of your console in your Resource list and clicking the Refresh cluster button. When the link between your
cluster and your console has been refreshed, click the Launch the IBM Blockchain Platform button.
Why am I getting the error Unable to authenticate with the enroll ID and secret you provided
when I create a new organization MSP definition?
What’s happening

When you attempt to create a new organization MSP definition from the Organizations tab, you experience the error Unable to
authenticate with the enroll ID and secret you provided .

This error occurs when the value that you specified for the enroll secret is not valid for the enroll ID that you selected in the
Generate organization admin certificate section of the panel.
How to fix it
Verify that you have selected the correct organization admin enroll ID from enroll ID drop down list and enter the correct value
for the enroll secret.
Why am I getting the error An error occurred when updating channel when I try to add an
organization to my channel?
What’s happening
When you attempt to add another organization to a channel, the update fails with the message An error occurred when
updating channel .

This error occurs when the selected Channel Updater MSP ID on the Update channel panel is not an admin of the channel.
How to fix it
On the Update channel panel, scroll down to the Channel Updater MSP ID and select the MSP ID that was specified when the
channel was created or specify the MSP ID that is the admin of the channel.
When I log in to my console, why am I getting a 401 Unauthorized error?
What’s happening
When I try to log in to my console, I am unable to access the console from my browser. If I check the browser logs, I can find the
error 401 unauthorized.

Your browser console session times out after 8 hours of inactivity. If a session becomes inactive, the console will prevent the
inactive user from performing any actions.
If your session has become inactive, you can try simply refreshing your browser. If that does not work, close the browser
including all tabs and windows. Open the URL again. You will be required to log in.
Note: As a best practice, you should have already stored your certificates and identities on your file system. If you happen
to be using an incognito window, all the certificates are deleted from the browser local storage when you close the
browser. After you log in again you will need to re-import your identities and certificates.
Why am I getting a Cluster linking is taking too long error when I try to link my
Kubernetes cluster in IBM Cloud to my IBM Blockchain Platform service instance?

What’s happening
After attempting to link my Kubernetes cluster on IBM Cloud to my IBM Blockchain Platform service instance, it fails with the
error Cluster linking is taking too long .

This issue can occur when your cluster is busy processing other requests and does not respond to the linking request in a timely
matter.
How to fix it
To resolve this problem you can run the helm reset command to delete the tiller and then try to link your cluster again. The
tiller is the helm mechanism that the blockchain deployer uses to set up components on your cluster. Run the following
command from your IBM Cloud CLI terminal:
bx api cloud.ibm.com
bx login
bx cs clusters
$(bx cs cluster-config <cluster_name> --export)
kubectl get deployments #test that the connection is working
helm reset
Attempt to link your cluster again. If it continues to fail, you should Contact Support.
What’s happening
The following error is shown on the console: "All SubConns are in TransientFailutre."

An Out of Memory (OOM) situation can cause this error.
How to fix it
To resolve this problem, you need to resize the peers and CouchDB containers to add more memory, such as 2000 MB memory
each. After resizing the memory, delete the peer pods so they will be re-created. Then try the scenario again. See
Considerations when reallocating resources for more information.
Why is my first invoke of a smart contract returns the following error: no suitable
peers available to initialize from?
What’s happening
When I try to invoke a smart contract from the Fabric SDK, the transaction fails and returns the following error:
error: [Network]: _initializeInternalChannel: no suitable peers available to initialize from Failed

to submit transaction: Error: no suitable peers available to initialize from

This error occurs if you have not configured an anchor peer on your channel. Unless you have manually updated your connection

profile, your application needs to use the Service Discovery feature to learn about the peers it needs to submit the transaction
to.
How to fix it
Use the following steps to configure anchor peers on your channel. Also, you should verify that you are submitting the
transactions against the correct channel and organization MSP id.
Why are my node operations fail to operate after I create my peer or ordering
service?
It is possible you may experience an error when managing an existing node. When that occurs, it is often useful to consult the
node logs.
What’s happening
For example, when you try to operate the node, the action might fail.

After creating a new peer or ordering service, depending on your cluster storage configuration, it may take a few minutes for the
nodes to be ready for operation.
How to fix it
Check your Kubernetes dashboard and ensure the peer or node status is Running . Then try your action again. If you are still
experiencing problems after the node is up, check your node logs for errors.

It is possible to experience this error under a variety of conditions.
What’s happening
The peer log includes:
[main] InitCmd -> ERRO 001 Cannot run peer because cannot init crypto, folder “/certs/msp” does not
exist`
or the ordering node log contains:
Failed to initialize local MSP: admin 0 is invalid [The identity does not contain OU [CLIENT], MSP:
[orderermsp],The identity does not contain OU [ADMIN], MSP: [orderermsp]]
This error can occur under the following conditions:
When you created the peer or ordering service organization MSP definition, you specified an enroll ID and secret
that corresponds to an identity of type peer and not client or admin. It must be of type client or admin.
When you created the peer or ordering service organization MSP definition, you specified an enroll ID and secret
that does not match the enroll ID or secret of the corresponding organization admin identity.
When you created the peer or ordering service, you specified the enroll ID and secret of an identity that is not type
'peer' or 'orderer'.
When you created the peer or ordering service, you associated an identity that does not have theadmin role.
Open your peer or ordering service CA node and view the registered identities listed in theRegistered Users table.

Delete the peer or ordering service and recreate it, being careful to specify the correct enroll ID and secret of a user that
has the peer or orderer role and associate an identity that has a role ofadmin with the node.
Note that before you create the peer or ordering service, you need to register an organization admin user, with a type
admin. Be sure to specify that same id as the enroll ID when you create the organization MSP definition. See these
instructions for registering peer identities and these instructions for registering orderer identities.
What’s happening
When you change the resources allocated to a CA, peer, or ordering node, or if you update the admin certificates for a node, the
pod has to restart in order for the changes to take effect. Or when a worker node is updated for maintenance and needs to
restart, the associated blockchain pods also need to be restarted. Sometimes, due to conditions on your Kubernetes cluster, the
pod restart can fail.

A component can fail to restart for a variety of reasons:
If another application in a cluster with constrained resources is in a pending state, and is prioritized higher than the
blockchain component, the blockchain pod cannot restart because the resources are consumed by the pending
application.
If the blockchain component needs to restart, but is on a worker node that has been "cordoned", meaning no new
components can be brought to that node, it cannot restart. A blockchain pod becomes unschedulable when the
Kubernetes scheduler is unable to find a node that can accommodate the resource requirements of the pod.
If there is a timeout between the kubelet, the node agent that runs on each node, and the Kubernetes master node, a pod
restart can fail.
The pod restart itself can time out when its worker node restarts and takes too long to mount the persistent volume claim
(PVC).
How to fix it
To enable the blockchain pod to restart successfully, you need to address the underlying cluster issues:
Ensure there are adequate resources available on worker nodes in the cluster. If not, deploy a new worker node with
increased resources.
After you resolve the cluster issues, delete the failing blockchain pod. When Kubernetes restarts the pod, it will attempt to
move the pod workload to another node with sufficient resources.
If the timeout between a kubelet and the master node cannot be resolved, open a support ticket with your cluster
provider.
What’s happening
Sometimes a node can fail to deploy, for example, due to lack of resources in your Kubernetes cluster. After you understand the
cause of the node deployment failure, you need to clean up the failed node in your cluster.
How to fix it
Do not attempt to use Kubernetes commands to remove the node. Instead, it is extremely important that you use the IBM
Blockchain Platform console or the APIs to remove the failed node to ensure that the associated metadata and storage are also
cleaned up.

What’s happening
You may need to view your smart contract, or chaincode, container logs to debug a smart contract issue.
How to fix it
Follow these instructions to view your smart contract container logs on IBM Cloud.
What’s happening
This problem can happen when you try to deploy a CA, peer, or ordering node that is configured with HSM and the deployment
fails. Or it can surface when a node that is configured for HSM stops working. The node, client, or SDK logs contain the following
error:
{"code":1000,"message":"Private key not found [pkcs11: 0x30: CKR_DEVICE_ERROR]"}"
or
{"code":1000,"message":"Private key not found [pkcs11: 0xB3: CKR_SESSION_HANDLE_INVALID]"}"

This problem happens when the PKCS #11 proxy that is associated with the HSM is unreachable due to a network problem or if
the proxy restarts after the node has connected to it.
How to fix it
To re-establish communications between the node and the proxy, restart the failing node by deleting the pod associated with
the node. A new pod will be created and the connection with the PKCS #11 proxy is restored. Use the following steps to restart
the failing node:
List the pods: kubectl get pods -n <NAMESPACE>

Delete the pod: kubectl delete pod -n <NAMESPACE> <PODNAME>
Replace:
<NAMESPACE> with the namespace where the associated pods are deployed. To find the namespace, open any CA node in
your console and click the Settings icon. View the value of the Certificate Authority endpoint URL. For example:
https://n2734d0-paorg10524.ibpv2-cluster.us-south.containers.appdomain.cloud:7054 . The namespace is
the first part of the URL beginning with the letter n and followed by a random string of six alphanumeric characters. So in
this example, the value of the namespace is n2734d0.
<PODNAME> with the Name of the failing pod that is visible in the list of pods returned by the previous command.
Why are my transactions returning an endorsement policy error: signature set did
not satisfy policy?
What’s happening
When I invoke a smart contract to submit a transaction, the transaction returns the following endorsement policy failure:
returned error: VSCC error: endorsement policy failure, err: signature set did not satisfy policy

If you have recently joined a channel and installed the smart contract, this error occurs if you have not added your organization
to the endorsement policy. Because your organization is not on the list of organizations who can endorse a transaction from the
smart contract, the endorsement from your peers is rejected by the channel. If you encounter this problem, you can change the
endorsement policy by upgrading the smart contract. For more information, see Specifying an endorsement policy and
Versioning a smart contract.
Why are the transactions I submit from VS Code failing with a No endorsement plan
available error?
What’s happening
Transactions submitted from VS Code fail with an error similar to:
Error submitting transaction: No endorsement plan available for {"chaincodes":[{"name":"hello-

world"}]}

This error occurs if you are using the Fabric Service Discovery feature but did not configure any anchor peers on your channel.
How to fix it
Follow step three of the private data topic in the Deploy a smart contract tutorial to configure your anchor peers.
Why are the transactions I submit from VS Code failing with an endorsement
failure?
What’s happening
My smart contract endorsement proposals from my peer are failing from my client application with the endorsement error
error: [Channel.js]: Channel:<channel_name> received discovery error:failed constructing descriptor for
chaincodes:<name:"chaincode-name"> or [ERROR] Error submitting transaction: No endorsement plan
available for {"chaincodes":[{"name":"MyAssetContract"}]}
Also in the endorsing peer logs I can see the error:
UTC [discovery] chaincodeQuery -> ERRO 23c Failed constructing descriptor for chaincode chaincodes:
<name:"chaincode-name">,: cannot satisfy any principal combination

This error occurs when the peer's enroll id type does not match the smart contract endorsement policy that was configured
when the smart contract was instantiated on the channel.
How to fix it
The only way to resolve this error is to delete the peer and create a new one with an enroll id that has the correct typepeer . You
can use the enroll id and secret from an existing user of type peer from the peer's CA or register a new user with type peer .
Follow the instructions in the Build a network tutorial to create a new peer identity with the correct type and peer.

What’s happening
A peer node has a timeout or connection refused error when trying to communicate with the orderer.

This problem can occur due to the network policies applied by the operator, which occurs when the environment variable
IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY is set to "true" .
How to fix it
Disable the network policies in your namespace. This should resolve connectivity issues with your nodes.
What’s happening
A CA, peer, or ordering node has a red status box, meaning there may be connectivity issues with the node. Ideally, when you
hover over any node, the node status should be Running .

This problem can occur due to the network policies applied by the operator, which occurs when the environment variable
IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY is set to "true" .
How to fix it
Disable the network policies in your namespace. This should resolve connectivity issues with your nodes.
What’s happening
You may need to disable the network policies in your namespace to address connectivity issues in your network.
How to fix it
Check if network policies have been applied in your namespace by running the following CLI command:
kubectl get netpol -n <NAMESPACE>
If the command returns a list of one or more network policies that you did not apply and/or you want to disable, first disable the
operator creation of network policies. Get the operator deployment spec in your namespace and check for environment variable
IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY :
kubectl get deploy ibm-hlfsupport-operator -n <NAMESPACE>
If it is present, remove the environment variable IBPOPERATOR_CONSOLE_APPLYNETWORKPOLICY :
kubectl edit deploy ibm-hlfsupport-operator -n <NAMESPACE>
Once the operator creation of the network policy has been disabled, delete the network policies from the namespace:
kubectl delete netpol -n <NAMESPACE> <NETWORKPOLICYNAME>

What’s happening
You are looking for the commands to delete a peer.
How to fix it
Use the following CLI command to identify and then delete and restart the failing peer:
List the pods: kubectl get pods --all-namespaces

Delete the pod: kubectl delete pod -n <NAMESPACE> <PODNAME>
Replace <NAMESPACE> with the name of your Kubernetes namespace or your OpenShift project.
What’s happening
All contracts were lost after the procedure to upgrade the smart contract container crashed.
How to fix it
Delete all the peer pods. This deletion triggers the peer to be created again and restarts the proxy.
What’s happening
I received an e-mail that my IBM Kubernetes service cluster is about to expire or its status is Expired . Or, you are not able to
access the console after 30 days.

Free Kubernetes clusters are only valid for 30 days.
How to fix it
It is not possible to migrate from a free cluster to a paid cluster. After 30 days you cannot access the console and all of your
nodes and certificates are deleted. See this topic on Kubernetes cluster expiration for information on what is happening and
what you can do.
After I deploy a node in the console, I'm seeing a message in my Kubernetes cluster
on IBM Cloud reporting that the pod has unbound immediate persistent volume
claims. Is this an error?
What’s happening
I see what looks like an error in my Kubernetes cluster on IBM Cloud reporting that a pod has unbound immediate persistent
volume claims and am worried that my node has failed to deploy.

More time is needed for the node to come up or you've possibly exceeded the maximum number of storage instances for your
IBM Cloud account.
How to fix it
Unbound immediate persistent volume claims are a normal part of the deployment process for any node, reflecting that the
persistent volume claim has been made but that the node itself has not yet deployed. Wait a few minutes for the node to deploy.
If it is still not resolved, run the following kubectl command to describe the persistent volume claim for your namespace:
kubectl describe pvc <pvc_name> -n <namespace>
If you see the following error, it is likely that you have reached your limit of storage volumes:
Backend Error:Your order will exceed the maximum number of storage volumes allowed. Please contact
Sales. Type:StorageOrderFailed, RC:500, Recommended Action(s):Wait a few minutes, then try re-creating
your PVC. If the problem persists, open an IBM Cloud support case.
See the troubleshooting topic on File storage and block storage: PVC remains in a pending state for more details.
After I deploy a node, I'm seeing a message in my Kubernetes cluster on IBM Cloud
reporting that the pod has hit a crash loop backoff. Is this an error?
I see an error in my Kubernetes cluster on IBM Cloud reporting that the pod has hit a crash loop backoff and am worried that my
node has failed to deploy.

This node has failed to deploy.
How to fix it
The node has failed to deploy. There can be several reasons for this, but you must go to your console, delete the node, and
attempt to redeploy it. Make sure you are using the correct MSP, enroll ID, and secret.

Getting support
IBM® Blockchain Platform provides several avenues for troubleshooting problems and getting support, which depend on your
IBM Blockchain Platform product, support plan and case severity.
Security incidents
IBM® Blockchain Platform provides the following methods for investigating and reporting security incidents:
Search known IBM security issues on the IBM Product Security Incident Response blog. You can filter the issues by
severity.
Report your security issue to the IBM Product Security Incident Response Team (PSIRT). Reporting methods for third-
parties and anonymous sources are also provided.
IBM support subscribers can log in and open a case with the appropriate severity. Refer to details, including IBM response
times, below in Submitting support cases.
General support
For all IBM Blockchain Platform offerings, it is recommended to first use free digital support resources to troubleshoot problems
and get help from IBM and the Hyperledger Fabric Community.
If your problem cannot be solved by any of the free digital support resources, consider the following approaches to get support
for the offerings that you use.
Submit a support case through IBM Cloud. For more information, see Submitting support cases.
IBM Blockchain Platform Visual Studio Code extension
Submit any issues in the IBM Blockchain Platform Visual Studio Code extension.
Resources and support forums

IBM Blockchain Service docs
IBM Blockchain Service docs, provides guidance on how to start with IBM Blockchain Platform. You can find corresponding
topics from the table of contents or search any term from the search bar.
Hyperledger Fabric resources
Hyperledger Fabric documentation, the Fabric community wiki, and the Fabric Jira dashboard provide more details about the
Fabric stack.
You can also post questions or check if your question was answered in Stack Overflow.
Developer resources
IBM Developer provides tutorials, code patterns, and videos for blockchain developers. Application developers can use the
Blockchain Design patterns to learn about common patterns and best practices for building applications that communicate with
blockchain networks.
Because IBM does not support using Hyperledger Composer for production implementation, you are encouraged to engage with
Hyperledger Composer community and Stack Overflow when you work on demos and proofs of concept.
Submitting support cases

For issues that are related to IBM Blockchain Platform for IBM Cloud, you can submit a support case in the IBM Cloud Service
Portal.
Note: If you need help with Hyperledger Fabric or your applications, you can make use of the community resources or
engage IBM Blockchain Services. It is recommended to use Hyperledger Composer solely for demos and proofs of
concept. IBM does not support networks that use Hyperledger Composer in production, including the Composer CLI,
JavaScript APIs, REST server, and Web Playground.
The response to your support case depends on your IBM Cloud support plan.
If you purchased Premium Support or Advanced Support, you can specify a severity level on your ticket from Sev-1 to
Sev-4. Sev-1 is the highest level of severity. Support cases with higher severity levels indicate more urgency and are
responded to more quickly by the support team. Ensure that the ticket severity is assigned based on the published criteria
that is defined in Case severity and response times. For more information, see IBM Cloud support plan offerings.
If you do not purchase support, your IBM Cloud Pay-As-You-Go or Subscription account comes with a freeBasic Support
plan. In this case, your support case is automatically registered as Sev-4.
Important: Before you open a support ticket, you need to gather your logs.
Follow these steps to submit a support case.
1. Log in to IBM Cloud Service Portal with your IBM ID.

2. Under Need more help? on the right of the page, click Create a Case.
3. Fill the Create Case form with your information at least for the following fields.
Choose Technical as your case type.
In the Category drop-down list, select Blockchain.
In the Subject field enter a summary of your issue.
In the Description field, describe your issue.
Attach any relevant logs or files to demonstrate your issue.
Click Email me updates to receive updates on the status of the ticket.
4. Click the Submit button. You will receive an email notification in a few minutes for this case.
You can find your previously submitted cases by clicking My Cases in the IBM Cloud Service Portal. Click and open a case to
check its status or provide additional information.

Site map
Getting started
Getting started with IBM Blockchain Platform
Which IBM Blockchain Platform offering is right for your business?
IBM Blockchain images
Next steps
Getting support
Getting started with IBM Blockchain Platform for IBM Cloud
What is the Blockchain Service?
Considerations
Video tutorial
Before you begin
Browsers
Resources required
Persistent storage considerations
Provision persistent storage
Configuring a custom storage class
Using Multizone (MZR) clusters with IBM Blockchain Platform
Pricing and Billing information
Choose your deployment process
Deployment options
Deploy from IBM Cloud
Deploy a Kubernetes cluster on IBM Cloud
Free IBM Kubernetes Service clusters
Create an IBM Blockchain Platform service instance in IBM Cloud
Step one: Create and name the instance
Step two: Link the instance to your Kubernetes cluster on IBM Cloud
Blockchain component deployment
(Optional) Add additional users to the console

Next steps
Updating the Kubernetes version of your cluster
How to assign Kubernetes access roles
Post-install instructions
Returning to your console from IBM Cloud
Deleting a service instance
Deploy from Red Hat Marketplace
What is Red Hat Marketplace?
Limitations
Before you begin
Step one: Apply the Security Context Constraint
Step two: Apply the image pull secrets
Step three: Deploy the IBM Blockchain Platform console
Use your own TLS Certificates (Optional)
Step four: Verify the console installation
Step five: Log in to the console
Removing your deployment
Next steps
Support
Create a project for your IBM Blockchain Platform deployment

What IBM Blockchain Platform offers
Supported IBM Cloud configuration
Fabric Component Support
Considerations
License and pricing
Getting started
Architecture reference

IBM Blockchain Platform on IBM Cloud Kubernetes Service Architecture
IBM Blockchain Platform on Red Hat OpenShift Architecture
Integrating with IBM Cloud and other third-party services
Compliance
Getting support
What is blockchain?
What is blockchain?
What's new
What's new
May 03, 2022

Peers
Ordering services
Channels
Smart contracts
Applications
An example network
Pricing
Pricing for IBM Blockchain Platform for IBM Cloud
Pricing model
Benefits of the new pricing model
Find out how to preview the platform free for 30 days
Key elements of cost
Pricing examples
Default resource allocations
Billing
IBM Cloud and IBM Blockchain Platform charges
Storage usage

Optimizing the cost of your nodes
Detailed pricing scenarios
Scenario comparisons
Security
Security
Security on the IBM Blockchain Platform console
Ports
Key management
API authentication
Best practices for security on the customer Kubernetes cluster
Network security
Internet Ports
Cluster and Operating System security
Storage
Data privacy
GDPR
Hyperledger Fabric Security
Enable network policy
High availability
High availability (HA)
Overview of potential points of failure in IBM Blockchain Platform
Peer considerations
Ordering service considerations
Certificate Authority (CA) considerations

HA Checklist
Potential points of failure
Single region HA
Multizone HA
Multi-region HA
Disaster recovery (DR)
Backup and recovery
Setting up multiregion High Availability (HA) deployments for peers
Overview
Configuration steps
Step one: Create the peer organization's CA and metadata in cluster one
Step two: Export the metadata and identities from cluster one
Step three: Import the metadata and identities in to cluster two and three
Step four: Create new peers in cluster two and three and join a channel
Setting up multiregion High Availability (HA) deployments for the ordering service
Before you begin
Deploy the ordering service in Region 1
Create the ordering service CA
Associate the CA admin identity
Use your CA to register identities
Create the ordering service organization MSP definition
Create single node ordering service in Region 1.
Add second ordering node in Region 1
Export components
Add a new ordering node in Region 2
Import components
Add third ordering node from Region 2
Export the ordering node

Add two new ordering nodes in Region 3
Import components
Add fourth and fifth ordering nodes from Region 3
Add the ordering nodes to the orderer system channel
Export the ordering nodes
Update the ordering service in Region 1, Region 2, and Region 3.
Next steps
Building a high availability Certificate Authority (CA)
Configuring CA replica sets
Deploying a PostgreSQL database
Considerations
Before you begin
Creating the PostgreSQL connection file
Creating an HA CA
Data residency
Data residency
How data is shared within an IBM Blockchain Platform network
A use case for data residency
Option one: Private data collections on a shared channel
Option two: Private data collections on a separate channel
Option three: A channel with all components in one country
Option four: A separate channel with only ordering nodes from one country
Considerations around using the IBM Blockchain Platform console
Reference material
FAQs
FAQs
Can IBM Blockchain Platform components interoperate with Hyperledger Fabric components on the same network? And
vice versa? And what is the support policy for networks that include both IBM Blockchain Platform components and open
source components?

How can I estimate the IBM Blockchain Platform sizing requirements for my development, test, and production
environments?
How does pricing work on the IBM Blockchain Platform for IBM Cloud?
What are the limitations of the free IBM Blockchain Platform using the IBM Cloud Kubernetes Service free cluster?
What regions or locations are available for the IBM Blockchain Platform for IBM Cloud?
What persistent file storage does IBM Blockchain Platform for IBM Cloud use by default?
Is it possible to deploy blockchain nodes to multiple clouds from a single blockchain console?
How do I get the latest Fabric version and Fabric functionalities on my IBM Blockchain Platform network?
I am currently using Hyperledger Fabric v1.4.x and want to move to IBM Blockchain Platform for IBM Cloud . Can I
continue to use Raft?
Can I migrate the blockchain components on my IBM Kubernetes service cluster to a Red Hat OpenShift cluster in IBM
Cloud?
What types of off-chain databases are supported with the IBM Blockchain Platform?
If service discovery is on, will an endorsement request be routed to any peer on the network?
Do ordering service Raft nodes use Transport Layer Security (TLS) for communication?
What benefits are available with the new smart contract lifecycle available on nodes and channels running on Fabric v2.x?
How can I check and interpret the status of my components through the Kubernetes command line?
Do you support using certificates from non-IBM Certificate Authorities?
Can I integrate my corporate LDAP server with the Certificate Authority (CA) in the IBM Blockchain Platform?

Where does IBM store the customer's logs and how long does IBM keep the audit logs for the blockchain platform
service?
Where can I see the price breakdown for IBM Cloud Kubernetes Service, Storage, and Blockchain in my monthly invoice?
Disclaimer
Disclaimer
IBM support statement
Open-source statement
Chaincode support statement
Getting started
Build a network
The structure of this network
Creating your peer organization's CA
Creating the peer organization MSP definition
Creating a peer
Step two: Create the ordering service
Ordering in the console
Creating your ordering service organization CA
Using your CA to register ordering service node and ordering service admin identities
Creating the ordering service organization MSP definition

Deploy the ordering nodes
Step three: Join the consortium hosted by the ordering service
Add the organization to the consortium
Step four: Create a channel
Step five: Join your peer to the channel
Next steps
Join a network
Creating your peer organization CA
Creating the peer organization MSP
Creating a peer
Step two: Add Org2 to an existing channel
Export the ordering service and its MSP
Import the ordering service
Step three: Join your peer to the channel
Step four: Creating a channel
Join the consortium hosted by the ordering service
Export your organization information
Import the organization definition
Add Org2 MSP to the ordering service consortium
Next steps
IBM Blockchain Platform getting started videos
Getting started with IBM Blockchain Platform 2.5.3

Deploy a smart contract using Fabric v2.x
Before you begin
Ensure peer is running Fabric v2.x image
Update MSPs in consortium to add organization-level endorsement policy
Create channel and join peers
Export and Import Membership Service Providers (MSPs)
Peer admin identity
Limitations
Can I continue to use the Fabric SDK to deploy my smart contracts?
What happens to my existing smart contracts?
Versioning smart contract definition and packages
Step three: Approve smart contract definition
Step four: Commit smart contract definition
How do I?
Specifying a smart contract endorsement policy
Versioning a smart contract
Important considerations when you update smart contracts
Private data
Implicit data collections
Deploy a smart contract using Fabric v1.4 (Deprecated)
Before you begin
Step two: Install a smart contract
Step three: Instantiate a smart contract

Step four: Send transactions by using your client applications
Connect with SDK
Specifying an endorsement policy
Upgrading a smart contract
How to upgrade a smart contract
Considerations when you upgrade smart contracts
Private data
Using the v2.4 Fabric Gateway peer service
Supported app development methods in Fabric v2.4
Fabric Peer Gateway documentation
Connecting to the Fabric Gateway peer service
Legacy model of developing applications
High-Level Programming Model APIs
Low-Level Fabric SDK APIs**
Application connectivity and availability
Network considerations
Application compatibility
SDKs
Smart contracts
Registering an application identity
Downloading your connection profile
Service discovery
Enrolling by using the SDK
Invoking a smart contract by using the SDK
Running the Commercial Paper sample
Prerequisites
Step one: Download the sample

Step three: Generate certificates for your wallet
Step four: Use the connection profile to build a Fabric gateway
Step five: Invoke the smart contract
Step six: Operate the sample as Digibank
Connecting to your network by using low-level Fabric SDK APIs
Highly available applications
Using indexes with CouchDB
Clock synchronization
Additional Resources
Certificate Authority (CA) options

Limitations
Process overview
Next steps
Objectives
Before you begin
Gather certificates
Build MSP definition
Import MSP into the console

Create and import the organization admin identity to the wallet
Deploy a blockchain node
Deploy peer
Next steps

Using IBM Cloud HSM
Process overview
What's next
Ansible Playbooks
What is Ansible
Getting started
Next steps
Prerequisites

Hints and Tips
Next steps
Summary
IBM Blockchain Platform console

Migrating to IBM Support for Hyperledger Fabric
What is happening?
Why is it happening?
How to transition licensing?
Planning and Considerations
Next steps
Administering your console
Refreshing your console
Adding and removing users from the console
Role to permissions mapping table
Assigning access roles to individual or groups of users in IAM
Updating the administrator email address
Configuring node logging
Before you begin
Customize logging
Viewing your logs
Viewing your console logs
Viewing your node logs
Viewing your smart contract container logs
Using IBM Log Analysis to view the node logs
Upgrading your nodes
Kubernetes cluster expiration
What types of advanced deployment options are available?

Before you begin
Allocating resources
CA deployment
Database and replica sets
Sizing a CA during creation
Customizing a CA configuration
Peer deployment
State database
Sizing a peer during creation
Customizing a peer configuration
Ordering node deployment
Sizing an ordering node during creation
Customizing an ordering service configuration
Using certificates from an external CA with your peer or ordering service
Before you begin
Option 1: Create a new peer or single-node ordering service using certificates from an external CA
Option 2: Create a five node ordering service using certificates from an external CA
Configuring a node to use a Hardware Security Module (HSM)
What capability does HSM add to my blockchain node?
Considerations when using HSM
Before you begin
Build a Docker image
Configuring a CA, peer, or ordering node to use the HSM
Advanced channel deployment and management
General options
Advanced options

Updating a channel configuration
Signature collection flow
Channel configuration parameters you can update
Tuning your ordering service
Block cutting parameters
Batch timeout
Other performance considerations
Adding and removing ordering service nodes
Overview
Create the CA and organization for the new node
Create the node
Console 2: export the Ordering Service_2 node
Console 1: add the Ordering Service_2 node to your console
Update channel1 to add the Ordering Service2 MSP and the Ordering Service_2 node
Add Ordering Service2 MSP to channel1
Add the node to the application channel
Join the node to the application channel
Removing ordering service nodes
Mapping to existing ordering nodes
Editing the peer configuration
Importing nodes, MSPs, and identities
Why import components?
Limitations
Exporting and importing in bulk
Gathering certificates or credentials
Exporting and importing admin identities into the Wallet
Importing an organization MSP definition
Importing a peer
Before you begin

How to import a peer
Importing a CA
Before you begin
How to import a CA
Importing an ordering service
Before you begin
How to import an ordering service
Importing nodes from a locally deployed network
Creating and managing identities
Managing Certificate Authorities (CAs)
Associating the identity of the CA admin
Registering identities
Creating new CA admins
Enrolling an identity
Using your TLS CA
Storing identities in your console wallet
Adding identities
Viewing and updating identities
Downloading certificates
Storing identities in a Hardware Security Module (HSM)
Associating identities
Viewing the contents of a signing certificate
Managing organizations
Understanding MSPs
Managing MSPs in the console
Creating an MSP for your organization
Downloading a connection profile
Including a certificate authority in a connection profile
Updating an organization MSP definition

Manually building an MSP JSON file
Importing an MSP
Adding an organization to a consortium
Creating and editing a channel
Updating an MSP in a channel definition
Removing an organization
Managing certificates
Overview
Node OU support
Part one: Enable Node OU support for an MSP definition
Part two: Enable Node OU support for the MSP on a channel
Automatic certificate renewal
Certificate types and actions
Manual certificate renewal
Renew the CA TLS certificate
Renew Peer enrollment and TLS Certificates
Renew ordering node enrollment and TLS certificates
Considerations for a single node ordering service
Renew MSP Admin certificate
Step one: Enroll new identity
Step two: Update organization MSP
Step three: Associate new admin identity on peer or ordering service
Step four: Update peer organization MSP on application channel
Step five: Update channel member on ordering service system channel
Step six: Update ordering service admin on ordering service system channel
Step seven: Update orderer organization MSP on channel
Peer and ordering node enrollment and TLS certificates

Peer and ordering node organization admin certificates
Bulk admin certificate renewal with Ansible playbooks
Expired certificates
How to fix expired organization admin certificates
Using the command line to view certificate expiration
Export an MSP
Import an MSP
Upgrading and deleting deployed nodes
Considerations when reallocating resources
Monitoring file storage
Adding storage
Upgrading to a new version of Fabric
Update your CAs
Update your orderers
Update your peers
Step one: Back up your ledger (optional)
Step two: Upgrade your nodes one at a time
Step three: Update SDKs and smart contracts
Step four: Update capabilities
Deleting components
Operating nodes with operations service
Considerations and limitations
Before you begin
Checking node health
Viewing the metrics
Viewing logging levels
Setting logging levels
osnadmin service endpoints

Removing a system channel
Benefits
Systemless orderers details
Removing an existing system channel
Upgrading Node.js chaincode
Developing smart contracts and applications

Developing smart contracts with IBM Blockchain Platform Developer Tools
Before you begin
Prerequisites
Step one: Guided tutorials in VS Code
Step two: Create a smart contract project
Do I need to update my smart contract for Fabric v2.x?
Step three: Package a smart contract
Exporting, importing, and deleting a smart contract package
Step four: Deploy a smart contract to a preconfigured Hyperledger Fabric network
Deploying a preconfigured Hyperledger Fabric network
Interacting with your smart contract
Connecting your applications to the preconfigured network
Step five: Test a deployed smart contract
Step six: Connect to your IBM Blockchain Platform network
Invoke a smart contract that has been instantiated or committed on your channels
Deploy a smart contract from VS Code
Adding wallets and users
Writing powerful smart contracts
What's new in the new lifecycle
Packages and definitions
Taking advantage of the ability for each organization to use a separate package
Updating smart contracts

Putting it all together
Smart contract development tooling
Installing a package and proposing a definition
Best practices for application development
Advanced tutorials
Limitations
Process overview
Next steps
Using IBM Cloud HSM
Process overview
What's next
Objectives
Before you begin

Gather certificates
Build MSP definition
Import MSP into the console
Create and import the organization admin identity to the wallet
Deploy a blockchain node
Deploy peer
Next steps
Using Ansible Playbooks

What is Ansible
Getting started
Next steps
Prerequisites
Hints and Tips
Next steps
Summary

IBM Log Analysis
Step one: Configure cluster-level logging
Step two: View the logs for your IBM Blockchain Platform nodes
View node logs
View smart contract logs
Summary
IBM Cloud Monitoring
Before you begin
Step one: Provision an instance of the IBM Cloud Monitoring service
Step two: Configure the Open Dashboard for monitoring your IBM Blockchain Platform nodes
Step three: Create a new dashboard
Copy the Overview by Container dashboard
Configure panels to view CPU and Memory usage
Configure panels to view disk usage
Create dashboards for the CA and ordering nodes
Step four: Configure alerts to monitor resource usage
Summary
Prometheus metrics
Before you begin
Step one: Create a Sysdig identity to access nodes
Step two: Provision an IBM Cloud Monitoring instance
Step three: Configure the TLS secret
Step four: Configure Prometheus settings
Step five: View Prometheus metrics

Overview
Backup considerations for each node type
Scheduling snapshots
Taking snapshots

Node snapshots
Restoring nodes
Sequencing restorations
Restoring a peer
Restoring an ordering node

Swagger
Before you begin
Authentication
Retrieving service credentials
Retrieving an access token
Forming your API request
Limitations
Building a network by using APIs
Creating a node within a specific zone
Creating a node with a custom configuration
Example: Creating a custom Certificate Authority
Create a high availability CA
Deploy a node that uses an HSM
Import a network by using APIs
Operating your CA with the Fabric CA client
Set up the Fabric CA client
Generate certificates with your CA admin
Registering the component identity with the CA
Registering your organization administrator
Generating the admin Membership Service Provider (MSP) folder
Registering the component identity with the TLS CA
Troubleshooting
Creating an organization MSP definition

Creating a configuration file
Retrieve the CA connection information
Provide your component enroll ID and secret
Provide the signCert of your organization administrator
CSR (Certificate Signing Request) hosts
Completing the configuration file
Importing an admin identity into the IBM Blockchain Platform console
API reference
API reference
Hyperledger Fabric
Hyperledger Fabric
Peers
Membership Service Provider
Ordering service
The Fabric SDKs
Transaction flow
Kubernetes
Kubernetes
Key Kubernetes objects
IBM Cloud Kubernetes Service
IBM Developer
IBM Developer

IBM Cloud storage

IBM Cloud storage
Glossary

Glossary
Approve
Asset
Block
CA
Chain
Chaincode
Channel
Client
Commit
Connection profile
Consensus
Consenter set
Console
Consortium
CouchDB
Current state
Dynamic membership
Endorsement
Endorsement policy
Genesis block
Gossip
HSM
Hyperledger Fabric
Install
Instantiate
Kafka
Ledger
LevelDB
Lifecycle endorsement policy

Member
MSP
Network
Node
Ordering node
Organization
Out of band
Peer
Propose
Quorum
Raft
SDK
Service credentials
Service discovery
Shim
SignCert
Smart contracts
Smart contract definition
Smart contract package
State database
Transaction
User
World state
Release notes
Release notes
28 Feb 2023
31 Jan 2023
04 Jan 2023
07 Dec 2022

08 Nov 2022
11 Oct 2022
13 Sept 2022
16 Aug 2022
19 July 2022
22 June 2022
01 June 2022
03 May 2022
05 Apr 2022
08 Mar 2022
08 Feb 2022
11 Jan 2022
14 Dec 2021
16 Nov 2021
26 Oct 2021
05 Oct 2021
10 Aug 2021
13 Jul 2021
16 Jun 2021
05 May 2021
13 Apr 2021
22 Feb 2021
12 Jan 2021
New logging configuration panel
08 Dec 2020
19 Nov 2020
02 Nov 2020
Fabric v2.x node upgrade
Support for Fabric v2.x smart contract lifecycle
Improvements for HSM support

Certificate renewal enhancements
Remove registered user from CA
1 Oct 2020
25 Aug 2020
14 July 2020
18 June 2020
Fabric peer and ordering node images
Elimination of Docker daemon dependency
Kubernetes version upgrade
20 May 2020
Support for Intermediate Certificate Authorities (CAs)
Updated connection profile
16 April 2020
Support for AWS HSM
24 March 2020
6 February 2020
11 December 2019
15 November 2019
06 November 2019
02 October 2019
21 August 2019
12 August 2019
10 July 2019
24 May 2019
9 May 2019
17 April 2019
3 April 2019
Known issues
Known issues

Troubleshooting
Troubleshooting
Why is my IBM Blockchain Platform user interface unable to connect to cluster after deployment (Ingress issue)?
Why are my console actions failing in my Chrome browser Version 77.0.3865.90 (Official Build) (64-bit)?
When I hover over my node, the status is Status unavailable or Status unknown , what does this mean?
My nodes, channels, smart contracts, and identities have disappeared from the console. How can I get them back?
Why am I getting the error Unable to authenticate with the enroll ID and secret you provided when I create
a new organization MSP definition?
Why am I getting the error An error occurred when updating channel when I try to add an organization to my
channel?
When I log in to my console, why am I getting a 401 Unauthorized error?
Why am I getting a Cluster linking is taking too long error when I try to link my Kubernetes cluster in IBM Cloud
to my IBM Blockchain Platform service instance?
Why is my first invoke of a smart contract returns the following error: no suitable peers available to initialize from?
Why are my node operations fail to operate after I create my peer or ordering service?
Why are my transactions returning an endorsement policy error: signature set did not satisfy policy?
Why are the transactions I submit from VS Code failing with a No endorsement plan available error?
Why are the transactions I submit from VS Code failing with an endorsement failure?

After I deploy a node in the console, I'm seeing a message in my Kubernetes cluster on IBM Cloud reporting that the pod
has unbound immediate persistent volume claims. Is this an error?
After I deploy a node, I'm seeing a message in my Kubernetes cluster on IBM Cloud reporting that the pod has hit a crash
loop backoff. Is this an error?
Getting support
Getting support
Security incidents
General support
Resources and support forums
Submitting support cases

Block Chain

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Block Chain

Uploaded by

Copyright:

Available Formats

IBM Cloud

IBM Blockchain Platform

Which IBM Blockchain Platform offering is right for your business?

IBM Blockchain Platform for IBM Blockchain Platform for

anywhere (2.5.3) IBM Cloud

What are my deployment options?

How is it billed? Contact us for pricing $0.29 USD per allocated

Can I connect with peers in other clouds? Yes Yes

Can my data center be on-prem and behind a Yes No

Can I use a console UI to deploy and manage my Yes Yes

Are APIs available for node management? Yes Yes

I am an experienced Fabric customer. Are peer, CA, Yes No

Table 1. Which offering is right for your business?

IBM Blockchain Platform 3

IBM Blockchain images

Getting started with IBM Blockchain Platform for IBM Cloud

What is the Blockchain Service?

Figure 1. The IBM Blockchain Platform components

IBM Blockchain Platform 4

Before you begin

IBM Blockchain Platform 5

Chrome Version 100.0.4896.127 (Official Build) (x86_64)

Cluster size recommendations

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

Table 1. Recommended cluster size on Kubernetes cluster on IBM Cloud

IBM Blockchain Platform 6

Component (all containers) CPU** Memory Storage (GB)

Ordering node 0.35 0.7 100

Operator 0.1 0.2 0

Console 1.2 2.4 10

IBM Blockchain Platform 7

Provision persistent storage

Configuring a custom storage class

kubectl patch storageclass <storageclass> -p '{"metadata": {"annotations":

Replace <storageclass> with the name of your storage class.

IBM Blockchain Platform 8

IBM File Storage

Using Multizone (MZR) clusters with IBM Blockchain Platform

Pricing and Billing information

Choose your deployment process

Deploy from IBM Cloud

IBM Blockchain Platform 9

Free IBM Kubernetes Service clusters

Create an IBM Blockchain Platform service instance in IBM Cloud

Creating an IBM Blockchain Platform service instance is a two step process.

Create and name the instance.

Step one: Create and name the instance

IBM Blockchain Platform 10

Blockchain component deployment

(Optional) Add additional users to the console

IBM Blockchain Platform 11

Updating the Kubernetes version of your cluster

How to assign Kubernetes access roles

Returning to your console from IBM Cloud

Your console opens in your browser.

Deleting a service instance

IBM Blockchain Platform 12

Deploy from Red Hat Marketplace

What is Red Hat Marketplace?

Before you begin

IBM Blockchain Platform 13

Figure 1. Install the operator in the openshift-operators namespace