Add an organization to your existing Hyperledger Fabric blockchain network using an easy tool

The Hyperledger Fabric first-network sample (variously called the "Build Your First Network" sample and the "e2e_cli" sample) showcases a fully scripted and end-to-end automated example of a basic blockchain use case tutorial sample. The sample provisions a Hyperledger Fabric blockchain network, deploys a smart contract (chaincode-Example02) application to the running network, and runs transactions against the deployed chaincode.

The provisioned Hyperledger Fabric blockchain network consists of two organizations, two peers per organization, and a single Solo ordering service. The network supports automatic provisioning of cryptographic material for peer and orderer organizations, automatic provisioning of channel artifacts, and channel joining by participating organizational peers.

In this tutorial, we show you how to add a third organization to an application channel with its own peers to an already running Hyperledger Fabric blockchain network, and join it to the channel.

Introducing the configtxlator tool

The configtxlator tool provides a true stateless REST API, independent of the SDK, to simplify configuration tasks in Hyperledger Fabric blockchain networks. The tool converts easily between different equivalent data representations/formats. For example, in one mode of tool operation, the tool performs conversions between the binary protobuf format to a human-readable JSON textual format, and vice-versa. Additionally, the tool can compute configuration updates based on the differences between two different sets of configurations transactions.

Set up your environment

For command-line configuration updates, make sure you have at least Version 1.4.1 or above of Hyperledger Fabric installed. These versions feature newer/enhanced capabilities coupled with numerous defect fixes. You can learn about the detailed features and defect fixes in each of version release notes documents.

Bring up first-network and make sure it is running correctly as shown in Figure 1.

Figure 1. first-network sample running successfully

Get into the CLI container interactively and check the peer version using the commands shown below inside the container:

docker exec -it cli /bin/bash
peer version

Figure 2. Verification of peer binary version inside the CLI container

Make sure the JQ tool is installed and working correctly in the CLI container by running the following commands inside the CLI container:

jq -version
jq

Figure 3. Running commands inside the CLI container to verify JQ tool installation

Make sure the configtxlator tool is available, verify the tool version, start the tool in the background, and verify that the tool is running correctly in the background, inside the CLI container, by running the following commands:

configtxlator version
configlator start &
netstat -ap

Figure 4. Verification and successful running of configtxlator tool inside the CLI container

Set and verify the following environment variables by running the following commands inside the CLI container:

export CHANNEL_NAME=mychannel
export ORDERER_CA=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem
echo $CHANNEL_NAME

echo $ORDERER_CA

Figure 5. Setting and verifying the environment variables inside the CLI container

Retrieve the configuration block that is currently configured by running the following command inside the CLI container:

peer channel fetch config config_block.pb -o orderer.example.com:7050 -c $CHANNEL_NAME --tls --cafile $ORDERER_CA

Figure 6. Retrieve the current configuration block

Run the following commands inside the CLI container to verify the correct retrieval of the current configuration block:

ls *.pb
file config_block.pb

Figure 7. Verification of the retrieved configuration block

Run the following command inside the CLI container to decode the configuration block into a human-readable version of the JSON object:

configtxlator proto_decode --input config_block.pb --type common.Block > config_block.json

Figure 8. Decode the configuration block as a JSON object and verify

Run the following command inside the CLI container to extract the payload portion of the configuration object as a JSON configuration object:

jq  .data.data[0].payload.data.config config_block.json > config.json

Figure 9. Extract the payload portion of the configuration JSON object and verify

Run the following command inside the CLI container to create a new configuration JSON object that unites the current configuration and the new organization, Org3, which is added to the consortium dynamically as shown in Figures 10 and 11:

jq -s '.[0] * {"channel_group":{"groups":{"Application":{"groups": {"Org3MSP":.[1]}}}}}' config.json org3.json > updated_config.json

Figure 10. Create a new configuration JSON object file

Figure 11. New configuration JSON object as viewed in the JSON editor with Org3 being added to the consortium

Run the following command inside the CLI container to encode the original configuration JSON object as a configuration object protobuffer, as shown in Figure 12:

configtxlator proto_encode --input config.json --type common.Config --output config.pb

Figure 12. Encode the original configuration JSON object as a configuration object protobuffer

Run the following command inside the CLI container to encode the updated configuration JSON object as a configuration object protobuffer, as shown in Figure 13:

configtxlator proto_encode --input updated_config.json --type common.Config --output updated_config.pb

Figure 13. Encode the updated configuration JSON object as a configuration object protobuffer

Run the following command inside the CLI container to determine the configuration update change, given the original and updated configuration protobuffer objects -- and then verify the resulting computed configuration update object, as shown in Figure 14:

configtxlator compute_update --channel_id $CHANNEL_NAME --original config.pb --updated updated_config.pb --output config_update.pb

Figure 14. Compute the configuration update change delta and verify the configuration update protobuffer object

Run the following command inside the CLI container to convert the configuration update object into a human-readable JSON object, and verify it as shown in Figure 15:

configtxlator proto_decode --input config_update.pb --type common.ConfigUpdate | jq . > config_update.json

Figure 15. Convert and verify the configuration update object as a JSON object

Run the following command inside the CLI container to wrap the configuration update JSON object into an envelope, resulting in a configuration JSON object with an envelope, and verify it as shown in Figure 16:

Figure 16. Configuration update JSON object with envelope

Run the following command inside the CLI container to encode the configuration update JSON object with envelope to a configuration object with envelope as a protobuffer, and verify it as shown in Figure 17:

configtxlator proto_encode --input config_update_as_envelope.json --type common.Envelope --output config_update_as_envelope.pb

Figure 17. Encode configuration update JSON object with envelope to configuration object with JSON as a protobuffer

Run the following commands inside the CLI container to set the environment of Org1, sign the configuration update transaction, and verify signing to be successful, as shown in Figures 18 and 19:

CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
CORE_PEER_TLS_KEY_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.key
CORE_PEER_LOCALMSPID=Org1MSP
CORE_PEER_TLS_CERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.crt
CORE_PEER_TLS_ENABLED=true
CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

peer channel signconfigtx -f config_update_as_envelope.pb

Figure 18. Org1 administrator role successfully signing the configuration update transaction

Figure 19. Org1 administrator role successfully submitting the configuration update signed transaction

Run the following commands inside the CLI container to set the environment and verify for Org2, as shown in Figure 20 (you can issue all of these commands at once):

export CORE_PEER_LOCALMSPID="Org2MSP"

export CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt

export CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp

export CORE_PEER_ADDRESS=peer0.org2.example.com:9051

Figure 20. Setting and verification of the Org2 environment inside the CLI container

Run the following command inside the CLI container to dynamically update the configuration by submitting the transaction and verifying its success, as shown in Figure 21:

peer channel update -f config_update_as_envelope.pb -c $CHANNEL_NAME -o orderer.example.com:7050 --tls --cafile $ORDERER_CA

Figure 21. Dynamically updating the configuration by submitting update transaction

Run the following command inside the CLI container to retrieve the successfully updated configuration block from runtime and verify successful operation, as shown in Figures 22 and 23:

peer channel fetch config config_block_Org3MSP.pb -o orderer.example.com:7050 -c $CHANNEL_NAME --tls --cafile $ORDERER_CA

Figure 22. Retrieve updated configuration from runtime

Figure 23. Verify updated configuration from runtime

Run the following command inside the CLI container to decode the updated configuration object into human-readable JSON format and search for the Org3MSP token to confirm successful dynamic update of the configuration, as shown in Figure 24:

configtxlator proto_decode --input config_block_Org3MSP.pb --type common.Block > config_block_Org3MSP.json

Figure 24. Decoding and verifying successful dynamic update of configuration

Run the following commands inside the CLI container to list and verify the dynamic configuration update task artifacts in JSON and protobuffer formats, as shown in Figure 25:

file *.pb
file *.json

Figure 25. Listing and verifying dynamic configuration update task artifacts in JSON and protobuffer formats

Run the following command outside of the CLI container to confirm the successful update of the configuration dynamically, as shown in Figure 26:

docker logs -f peer0.org1.example.com

Figure 26. Verifying successful configuration update dynamically from container log

Run the following command from outside of the CLI container to determine the locations of the container logs in JSON format for detailed review, verification, and analysis, as shown in Figure 27:

docker inspect --format='{{.LogPath}}' dev-peer1.org2.example.com-mycc-1.0
docker inspect --format='{{.LogPath}}' dev-peer0.org1.example.com-mycc-1.0
docker inspect --format='{{.LogPath}}' dev-peer0.org2.example.com-mycc-1.0
docker inspect --format='{{.LogPath}}' cli
docker inspect --format='{{.LogPath}}' peer0.org2.example.com
docker inspect --format='{{.LogPath}}' peer1.org2.example.com
docker inspect --format='{{.LogPath}}' orderer.example.com
docker inspect --format='{{.LogPath}}' peer0.org1.example.com
docker inspect --format='{{.LogPath}}' peer1.org1.example.com

Figure 27. Determining the location of the container JSON formatted log files

Conclusion

Congratulations! You have successfully used the encoding and decoding features of the configtxlator tool to add a third organization with its own peers to the application channel of an already running Hyperledger Fabric blockchain network. You have verified and validated the successful addition of this new organization to your channel configuration.

Now that you know how to add an organization to an existing Hyperledger Fabric blockchain network consortium, you can now add this new organization to a channel so that the organization can fully participate in blockchain network activities. You are also ready to review, understand, and work through the tutorial Adding an Org to a Channel in the Fabric docs to achieve the above outcome.

Acknowledgments

The authors gratefully thank IBM Blockchain development/research professionals, IBM digital content development editorial and graphics professionals, and IBM executive/management team for giving us opportunity to work on this content.