Before diving into how to deploy Hyperledger Fabric on Kubernetes we need to understand some basics about Hyperledger Fabric.
What is Hyperledger Fabric
Hyperledger Fabric is an open source enterprise-grade permissioned distributed ledger technology (DLT) platform. Fabric has a very modular and configurable architecture and it is the first DLT platform to support smart contracts authored in general-purpose programming languages.
It is a restricted access blockchain designed to maintain transparency among a network of organizations that lack complete mutual trust.
Network Topology of HLF
Hyperledger Fabric (HLF) is primarily composed of the following key elements:
Certificate Authority (CA)
It plays a vital role in managing digital identities and maintaining the security and integrity of the network by issuing, validating, and managing certificates.
Typically CA nodes form a tree-like topology with Root CA at the top.
Root CA
It is a self-signed instance which issues certificates to all other organisations in the network.
Intermediate Certificate Authority (ICA)
CAs that belong to other organisations, essentially the Intermediate Certificate Authority (ICA) are signed by the Root CA. All the other nodes and users in the network are signed by the ICA.
TLS CA
It issues certificates to orderer and peers to enable the TLS communication in the network.
Orderers
It forms an ordering service which is responsible for keeping the blockchain state consistent and final. Orderers maintain access to the channels and keep a system channel that contains access control lists (ACLs) of organizations that can create channels. They restrict who can configure, read, and write data to particular channels.
Peers
They are the fundamental elements in a HLF Network as they manage ledgers and smart contracts.
Peers take care of proposal, endorsement, validation and commitment of a transaction in the HLF network. A peer belongs to one organization, can belong to multiple channels, and can host multiple ledgers and smart contracts.
They forward smart contract calls to dedicated chaincode containers in the network and update the network state on the basis of smart contract results. They also connect to the orderers to receive new blocks for transactions or can do p2p communication through gossip protocol.
Channels
A HLF channel is a private “subnet” of communication between two or more specific network members, for the purpose of conducting private and confidential transactions. All peers belonging to a channel have access to the same data and smart contracts. There is no access to it outside the channel.
Now, since we have a basic idea about HLF and its key components we can move on to deploying HLF on kubernetes using Falcon.
What is Falcon
Falcon is an open source, hyperledger fabric deployment helper designed to streamline the deployment and management of Hyperledger Fabric based blockchain networks on Kubernetes clusters.
The key features provided by Falcon are:
- CA Management (Root CA, TLS CA & Intermediate CAs)
- Peer Creation
- Orderer Creation
- Channel Management
- Chaincode Lifecycle Management (Install, Approve, Commit and CC Upgrades)
- Cryptographic operations support and certification management
- Domain Name support and SNI Based Routing
- Ingress resource provisioning
- File Registry support for centralised config files
- Support for Hyperledger Fabric 2.3+
- Multi-zone, Multi-DC, Private Network (On-prem DCs) deployment support.
Steps to deploy a HLF Network on kubernetes cluster
Prerequisites
- Deploy nginx ingress with the ingress service exposed by two Nodeports for Ports: 80/TCP, 443/TCP Depending on whether you are deploying on a public cloud or on your infrastructure in a data center, you can deploy an ingress service with a cloud native load-balancer or NodePort to allow access to the Ingress Controller. You can refer to https://platform9.com/learn/v1.0/tutorials/nginix-controller-via-yaml for a detailed explanation on the deployment.
- Edit the ingress deployment to enable the ssl passthrough
kubectl edit deployments.apps -n ingress-nginx ingress-nginx-controller
- Add Configurable DNS You need to add custom DNS zones that are resolvable from the pods. If you're using CoreDNS, follow this guide to add custom zones on your Kubernetes cluster https://coredns.io/2017/05/08/custom-dns-entries-for-kubernetes/. If deploying to GKE on GCP, you can make use of CloudDNS private zones.
-
Add the
A record(s)
that points to the server(s) where the Ingress is listening. It must be a wildcard DNS entry. Eg, If your domain name ismy-hlf-domain.com
and you have the worker node as172.100.1.2
. Then you need to create a DNS entry *.my-hlf-domain.com to point to above IP. This is a must have configuration and make sure that wildcard DNS queries are resolving properly. If you're in any public cloud platform, then hard coding the worker node IP in the DNS is not a reliable approach since the worker node can be changed at any time. In that case, you can deploy an Internal Cloud LB. -
Provision a
storageclass
that supports dynamic volume provisioning like rook-ceph or standard.
HLF Network
Clone the falcon repository and navigate to the root directory to begin the deployment using the sample example.`
- Deploy a filestore server
The filestore server is the nginx deployment with custom rules to support uploading over curl which stores common artifacts like chaincode, collection config file etc.
helm install filestore -n filestore helm-charts/filestore/ -f examples/filestore/values.yaml --create-namespace
You can check if your filestore server is up and running with
kubectl get pods -n filestore
The output should be something like
- Deploy Root CA
Create the orderer namespace in which we will deploy the Root CA. Also create a kubernetes secret with user and password as keys for this ROOTCA server.
kubectl create ns orderer
kubectl -n orderer create secret generic rca-secret --from-literal=user=rca-admin --from-literal=password=rcaComplexPassword
Deploy the Root CA Server
helm install root-ca -n orderer helm-charts/fabric-ca -f examples/fabric-ca/root-ca.yaml
This will deploy the root-ca server for you and the server will be available at https://root-ca.my-hlf-domain.com
. To verify the server, you can get into any running pod in the cluster and send a curl request as below;
curl https://root-ca.my-hlf-domain.com:<HTTPS-INGRESS-PORT>/cainfo --insecure
- Deploy TLS CA
Create a kubernetes secret for the TLSCA and deploy the tls ca server.
kubectl -n orderer create secret generic tlsca-secret --from-literal=user=tls-admin --from-literal=password=TlsComplexPassword
helm install tls-ca -n orderer helm-charts/fabric-ca -f examples/fabric-ca/tls-ca.yaml
This will deploy a tls ca server for you and the server will be available at https://tls-ca.my-hlf-domain.com
which can be verified in the same way as root ca by hitting a curl request.
- Create Root CA Identitites
helm install rootca-ops -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/rootca/rootca-identities.yaml
This step will register your initialpeerorg, orderer and org1, org2 identities with the Root CA.
Check the pods and wait for the jobs to successfully get completed.
- Create TLS CA Identities
helm install tlsca-ops -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/tlsca/tlsca-identities.yaml
This step will register your orderer0, orderer1, orderer2 and peer0, peer1, peer2 of initialpeerorg, org1 and org2 with the TLS CA.
Check the pods here as well and wait for the jobs to successfully get completed.
- Deploy Orderer ICA
This will deploy the Orderer ICA server which registers itself with Root CA.
Before deploying the Orderer ICA you need to create a secret with same username and password as being used while registering the ica-orderer identity with the root ca.
kubectl -n orderer create secret generic orderer-secret --from-literal=user=ica-orderer --from-literal=password=icaordererSamplePassword
Now we need to apply the helm chart to deploy Orderer ICA.
helm install ica-orderer -n orderer helm-charts/fabric-ca -f examples/fabric-ca/ica-orderer.yaml
- Deploy Initial peer org ICA
This will deploy the Initial Peer Org ICA server which registers itself with Root CA.
Similar to Orderer ICA we need to create the namespace and the secret here as well.
kubectl create ns initialpeerorg
kubectl -n initialpeerorg create secret generic initialpeerorg-secret --from-literal=user=ica-initialpeerorg --from-literal=password=initialpeerorgSamplePassword
Now we need to apply the helm chart to deploy the Initial Peer Org ICA.
helm install ica-initialpeerorg -n initialpeerorg helm-charts/fabric-ca -f examples/fabric-ca/ica-initialpeerorg.yaml
Check the init container logs to make sure the authentication and ica enrollment is successful.
- Create Orderer identities with ica-orderer
This step will register orderer identities i.e. orderer0, orderer1, orderer2 with the orderer-ica.
helm install orderer-ops -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/orderer/orderer-identities.yaml
- Create Initialpeerorg identities with ica-initialpeerorg
This step will register the initialpeerorg identities i.e admin, peer0, peer1, peer2 identities with the initialpeerorg-ica.
helm install initialpeerorg-ops -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/identities.yaml
- Generate Genesis block & Channel transaction file
This step will create the Genesis block
which is the first block in any blockchain based system and a channel transaction
file which contains channel name and the consortium which is allowed to use the channel.
helm install cryptogen -n orderer helm-charts/fabric-ops/ -f examples/fabric-ops/orderer/orderer-cryptogen.yaml
- Deploy Orderers
This will deploy your network's orderer.
helm install orderer -n orderer helm-charts/fabric-orderer/ -f examples/fabric-orderer/orderer.yaml
Note: Disable metrics in the yaml if you do not have CRDs and ServiceMonitor installed on your kubernetes cluster.
- Deploy Peers on Initial peer org
helm install peer -n initialpeerorg helm-charts/fabric-peer/ -f examples/fabric-peer/initialpeerorg/values.yaml
After successful deployment of the Peers, you will get 3 peers in initialpeerorg namespace. Each of these peers will have 1 Init container and 3 app containers (Fabric Peer, Dind & CouchDB). If everything went fine, then you'll see some successful connectivity logs in the peer0-initialpeerorg-0.
- Create channel
This step creates a channel named mychannel
helm install channelcreate -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/channel-create.yaml
You will be able to see similar logs after the successful completion of the job.
- Update Anchor peers of Initial peer org
helm install updateanchorpeer -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/update-anchor-peer.yaml
This updates the anchor peers of the initialpeerorg which enable communication between peers of different organizations and discover all active participants of the channel.
- Install chaincode on Initialpeerorg Peers
Before you install chaincode , you need to upload the packaged chaincode file to the filestore under your project directory and give the rwx permission to the file.
kubectl cp <chaincode.tar.gz> filestore/<filestore-pod-name>:/usr/share/nginx/html/yourproject
Change the name of the chaincode tar file accordingly in the install-chaincode.yaml
helm values file at Values.cc_tar_file
.
To install chaincode run
helm install installchaincode -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/install-chaincode.yaml
Once your job is completed you can check the logs to assure successful installation
Deploy Org1 Environment
Deploying more organisations has the similar steps as the initialpeerorg as:
- Deploy Org1 ICA
- Add Org1 to the network
Once the new organisation ica has been deployed successfully we need to add this new org to the network. For that, you need to run the following Job in initialpeerorg. Comment out the org2 section from the Values.organizatons array in the values file examples/fabric-ops/initialpeerorg/configure-org-channel.yaml for now since we have not deployed the Org2 yet.
helm install configorgchannel -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/configure-org-channel.yaml
- Create Org1 identities with ica-org1
- Deploy Peers on Org1
- Install ChainCode on Org1 Peers
- Update Anchor peers of Org1
Similarly you can deploy org2 environment as well.
Approve & Commit Chain Code
Approve & Commit requires collection-config optionally. You can manage it through the variable require_collection_config: "true". If you make it as true, then you must upload a collection config file to the filestore under your project directory.
Sample chaincode lies at examples/files/collection-config.json
Note :- if you're changing the collection-config, then kindly update the sha256sum value under Values.collection_config_file_hash.
- Approve Chaincode on Initialpeerorg
Ensure that you have updated the name, version and package id of the chaincode in
examples/fabric-ops/initialpeerorg/approve-chaincode.yaml
if you have uploaded your own collection-config file:
- cc_name
- cc_version
- cc_package_id
Run the below command to approve chaincode:
helm install approvechaincode -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/approve-chaincode.yaml
Similarly you need to approve the chaincode from all deployed orgs using their respective approve scripts.
- Commit Chaincode on Initialpeerorg
Ensure that you have updated the name, version and package id of the chaincode in
examples/fabric-ops/initialpeerorg/commit-chaincode.yaml
if you have uploaded your own collection-config file.
- cc_name
- cc_version
- cc_package_id
Run below command to commit the chaincode:
helm install commitchaincode -n initialpeerorg helm-charts/fabric-ops/ -f examples/fabric-ops/initialpeerorg/commit-chaincode.yaml
Voila!!! You have your HLF Network Setup up and running...
To sum up, this comprehensive guide has taken you through a detailed journey, unraveling the essence of Hyperledger Fabric (HLF), its pivotal components, and the powerful tool Falcon.
Remember, diving into the Falcon repository (https://github.com/npci/falcon) can provide deeper insights and support as you venture further into this transformative realm. Embrace the possibilities, implement the steps outlined, and witness the empowerment that Falcon brings to the deployment of Hyperledger Fabric on Kubernetes.
Happy Learning.
Top comments (1)
How do I stop the deployment? Will the deployment still work if I just stop the Kubernetes cluster and start it the next day?