This lab will show you how to deploy your Hyperledger-based business network on IBM Container Services on Bluemix.
IBM Container Services is a hosted container service on IBM's Bluemix Cloud platform, using open source Docker technology. It uses Kubernetes clusters to orchestrate, schedule and manage those containers.
Deploying Hyperledger in this way is fine for development and proof-of-concept work, but it is not suitable for production Blockchain workloads. For that you can use the IBM Blockchain Platform, which is a highly available, secure and resilient managed Blockchain service on IBM Cloud. See here for more details.
As you'll be interacting with Kubernetes, IBM Bluemix and Hyperledger Composer in this lab, you need to install three command line tools at the levels shown (or higher):
- kubectl: v1.7 (the Kubernetes command line tool)
- bx: v0.5 (the Bluemix command line tool).
- Hyperledger Composer CLI: always use the latest version.
Install kubectl from https://kubernetes.io/docs/tasks/tools/install-kubectl/ - use the section titled Install kubectl binary via curl. You will need to select your OS and follow some basic instructions to download a file, mark it as executable, and move it into position.
Install bx from
https://console.bluemix.net/docs/cli/reference/bluemix_cli/index.html#install_bluemix_cli - use the command shown in the Online installation section.
Validate the installations with kubectl version and bx -v.
Now add the container service plugin - this will let you interact with the IBM Container Service. Add the repo first (this tells the following command where to find the plugin to be installed) - you may get a message saying it already exists, if so that's fine.
bx plugin repo-add bluemix https://plugins.ng.bluemix.net
bx plugin install container-service -r bluemixInstall the Hyperledger Composer CLI tool with
npm install -g composer-cliNB: don't try to install this with sudo, it will cause errors.
Clone this git repository to your local machine
git clone https://github.com/idpattison/hyperledger-ibmcs.git
cd hyperledger-ibmcsPoint the Bluemix CLI at the API endpoint for your Bluemix setup, then login
bx api api.ng.bluemix.net
bx loginThis will ask for your userid and the account password.
NB: the API endpoint used is for IBM's US South region. If you need to use another region you will need to replace ng in the API with the code for that region, e.g. eu-gb for the UK.
You will be asked to select an organisation (usually your email address) and a space (call it something like 'blockchain'). If you don't get asked, you can specify them with
bx target -o <org-name> -s <space-name>If you'd like to you can create a new space with the command bx iam space-create <space-name>
Now create the cluster on the IBM Container Service
bx cs cluster-create --name blockchainThis could take up to 30 minutes. You can check progress with
bx cs clustersOnce the State shows normal, it's done. You should see something like this:
Listing clusters...
OK
Name ID State Created Workers
blockchain 0783c15e421749a59e2f5b7efdd351d1 normal 2017-05-09T16:13:11+0000 1Once that's done, you can check the status of the worker node:
bx cs workers blockchainThis will show the public and private IP addresses. Note down the public IP address, as you will use this later to access the Blockchain network.
Issue the following command
bx cs cluster-config blockchainThe output will contain an EXPORT command which will point your local kubectl to the cluster. Copy and paste that command into the command line and run it. It will be something like this:
export KUBECONFIG=/home/*****/.bluemix/plugins/container-service/clusters/blockchain/kube-config-prod-dal10-blockchain.ymlThe kube-configs directory defines a Blockchain implementation which consists of:
- Hyperledger Fabric (2 peers, 2 databases, an orderer and a CA)
- Hyperledger Composer Playground
- Hyperledger Composer Rest Server
- utility containers for creating the keys and certificates
- utility containers for creating and joining a channel
- utility containers for installing and instantiating the test chaincode
- persistent storage to allow containers to share cryptographic material
To deploy the Blockchain:
cd scripts
./create_all.sh --with-couchdbOnce that's complete you can use the Kubernetes Dashboard to explore the services and pods which have been created. Run
kubectl proxyNow browse to http://localhost:8001/ui and you will see the dashboard.
You can get all of this information from the command line (try kubectl get pods -a), but it's convenient to have it all just a few clicks away.
We're going to deploy the business network, but to do that we need a connection profile to tell our local Hyperledger Composer CLI where to deploy it. Local connection profiles are stored in ~/.composer-connection-profiles/ by default
Create a new connection profile directory for IBM Container Services and copy the example profile.
mkdir ~/.composer-connection-profiles/ibmcs
cp profile/connection.json ~/.composer-connection-profiles/ibmcsEdit it to use the public IP address of your container cluster - the one from bx cs workers blockchain.
When the Hyperledger instance was deployed to IBM Container Service, a set of cryptographic credentials was created. We need to copy some of those off the peer so we can use it locally.
Start by getting the container name of the Org1 peer - it will be something like blockchain-org1peer1-1820571918-bdqrv.
kubectl get podsNow extract two files from that peer - these are the certificate and key for the admin user. You need to use the container name you found in the previous step.
kubectl cp blockchain-org1peer1-xxxxxxxxxx-xxxxx:/shared/crypto-config/peerOrganizations/org1.example.com/users/Admin\@org1.example.com/msp/signcerts/Admin@org1.example.com-cert.pem cert.pem
kubectl cp blockchain-org1peer1-xxxxxxxxxx-xxxxx:/shared/crypto-config/peerOrganizations/org1.example.com/users/Admin\@org1.example.com/msp/keystore/key.pem key.pemImport that identity into the local credential store. Clear out the store first to remove any old keys.
rm -rf ~/.composer-credentials/*
composer identity import -p ibmcs -u PeerAdmin -c cert.pem -k key.pemAn example business network is provided, or you can use your own. Make sure that composer-cli is at the latest version, or you will get compatibility errors.
composer archive create -a digital-property.bna -t dir -n business-network/
composer network deploy -a digital-property.bna -p ibmcs -i PeerAdmin -s anythingNB: if you want to update an existing business network you need to use
composer network update:
composer archive create -a digital-property.bna -t dir -n business-network/
composer network update -a digital-property.bna -p ibmcs -i PeerAdmin -s anythingWhen the Composer REST server starts, it reads the model information from the business network which is deployed in the Blockchain. Therefore you can't start it until after you have deployed the business network.
That's the reason we didn't deploy the REST server along with all the other services; we're going to do that now.
Run the following command, adding in your business network name (that's the one defined in the package.json file, not necessarily the file name).
create/create_composer-rest-server.sh <business-network-name>Examine the running pods (either with the Kubernetes Dashboard or kubectl get pods) to see that the REST server has started. View the logs from the Dashboard (or use kubectl logs <container-name>) to ensure that it is serving on port 3000 - this will be exposed externally as port 31090.
Now access the Composer REST server explorer; browse to http://your-ip-address:31090/explorer
Congratulations! You've successfully deployed a Hyperledger Fabric Blockchain and a business network to IBM Container Services, and exposed it as an API.
You can remove the containers you deployed via Kubernetes with a single script.
cd scripts
./delete_all.sh