Add a new peer to an existing organization

This guide explains how to add a new general (non-anchor) peer to an existing organization in a Hyperledger Fabric network using two methods:

1. Using the add-peer.yaml playbook: This method involves running an Ansible playbook that automates the process of adding a new peer to the network.

2. Using helm install: This method involves using the helm install commands to directly add a new peer to the network.

Prerequisites

• A fully configured Fabric network with Orderers, Peers, Peer Organization and the Channel that the new peer will join.
• Corresponding crypto materials present in Hashicorp Vault or Kubernetes secrets.
• Hyperledger Bevel configured.

Method 1: Using the add-peer.yaml playbook

1. Additional Considerations

   Consider the following points when adding the new peer on a different cluster:

   • The CA server is accessible publicly or at least from the new cluster.
   • The CA server public certificate is stored in a local path and that path provided in network.yaml.
   • There is a single Hashicorp Vault and both clusters (as well as ansible controller) can access it.
   • Admin User certs have been already generated and stored in Vault (this is taken care of by deploy-network.yaml playbook if you are using Bevel to setup the network).
   • The network.env.type is different for different clusters.
   • The GitOps release directory gitops.release_dir and gitops.component_dir are different for different clusters.

2. Update Configuration File

   • Edit the network.yaml file to include the new peer with the following details:
     • peerstatus: new
     • org_status: existing
     • Organization details (name, CA address, MSP ID, etc.)
     • Orderer information, if you are going to install/upgrade the existing chaincodes.
   • Existing peer(s) should have peerstatus: existing
   • Refer to the networkyaml-fabric.md guide for details on editing the configuration file.

   Snippet from network.channels section below:

     # The channels defined for a network with participating peers in each channel
     channels:
     - channel:
       consortium: SupplyChainConsortium
       channel_name: AllChannel
       channel_status: new
       osn_creator_org: # Organization name, whose orderers will create the channel. This field is only used with version 2.5
         name: supplychain 
       chaincodes:
         - "chaincode_name"
       orderers: 
         - supplychain
       participants:
       - organization:
         name: carrier
         type: creator       # creator organization will create the channel and instantiate chaincode, in addition to joining the channel and install chaincode
         org_status: existing  # org_status must be existing when adding peer
         peers:
         - peer:
           name: peer0
           type: anchor
           peerstatus: existing    # old peers should have status as existing
           gossipAddress: peer1.carrier-net.org3proxy.blockchaincloudpoc.com:443  # Must include port, External or internal URI of the gossip peer
           peerAddress: peer0.carrier-net.org3proxy.blockchaincloudpoc.com:443 # Must include port, External URI of the peer
         - peer:
           name: peer1
           type: nonanchor
           peerstatus: new         # new peers should have status as new
           gossipAddress: peer0.carrier-net.org3proxy.blockchaincloudpoc.com:443  # Must include port, External or internal URI of the gossip peer
           peerAddress: peer1.carrier-net.org3proxy.blockchaincloudpoc.com:443 # Must include port, External URI of the peer
         ordererAddress: orderer1.supplychain-net.org1proxy.blockchaincloudpoc.com:443             # Must include port, External or internal URI of the orderer   
       - organization:
         name: supplychain
         type: joiner
         org_status: existing
         peers:
         - peer:
           name: peer0
           type: anchor
           peerstatus: existing    
           gossipAddress: peer1.supplychain-net.org1proxy.hlf.blockchaincloudpoc-develop.com:443
           peerAddress: peer0.supplychain-net.org1proxy.hlf.blockchaincloudpoc-develop.com:443
         - peer:
           name: peer1
           type: nonanchor
           peerstatus: existing    
           gossipAddress: peer0.supplychain-net.org1proxy.hlf.blockchaincloudpoc-develop.com:443
           peerAddress: peer1.supplychain-net.org1proxy.hlf.blockchaincloudpoc-develop.com:443
         ordererAddress: orderer1.supplychain-net.org1proxy.hlf.blockchaincloudpoc-develop.com:443 
   

   and from network.organizations section below:

     # Allows specification of one or many organizations that will be connecting to a network.
     # If an organization is also hosting the root of the network (e.g. doorman, membership service, etc),
     # then these services should be listed in this section as well.
     organizations:
       # Specification for the Existing Peer organization.
       - organization:
         name: carrier
         country: GB
         state: London
         location: London
         subject: "O=Carrier,OU=Carrier,L=51.50/-0.13/London,C=GB"
         external_url_suffix: org3proxy.blockchaincloudpoc.com
         org_status: existing  # org_status must be existing when adding peer
         orderer_org: supplychain # Name of the organization that provides the ordering service
         ca_data:
           certificate: /path/carrier/server.crt                           # CA Server public cert must be provided when adding peer on new cluster
         ..
         ..
         services:
           - peer:
             name: peer0
             type: anchor    # This can be anchor/nonanchor. Atleast one peer should be anchor peer.    
             gossippeeraddress: peer1.carrier-net.org3proxy.blockchaincloudpoc.com:443 # No change from original configuration
             peerAddress: peer0.carrier-net.org3proxy.blockchaincloudpoc.com:443 # Must include port, External URI of the peer
             peerstatus: existing    # old peers should have status as existing
             cli: disabled           # Creates a peer cli pod depending upon the (enabled/disabled) tag.          
             ..
             ..
           - peer:
             name: peer1
             type: nonanchor    # This can be anchor/nonanchor. Atleast one peer should be anchor peer.    
             gossippeeraddress: peer0.carrier-net.org3proxy.blockchaincloudpoc.com:443 # Must include port, External address of the existing anchor peer
             peerAddress: peer1.carrier-net.org3proxy.blockchaincloudpoc.com:443 # Must include port, External URI of the peer
             peerstatus: new     # new peers should have status as new
             cli: disabled       # Creates a peer cli pod depending upon the (enabled/disabled) tag.          
             ..
             ..
   

3. Run Playbook

   Execute the following command to run the add-peer.yaml playbook:

   ansible-playbook platforms/hyperledger-fabric/configuration/add-peer.yaml --extra-vars "@path-to-network.yaml"
   

   Replace path-to-network.yaml with the actual path to your updated network.yaml file.

   This will add a new peer and the new peer will join the channel provided in the existing Fabric network.

Method 2: Using helm install

1. Update the fabric-peernode values.yaml file

   Following changes are must in the values.yaml file for a new peer to be added to the network:

   • certs.settings.createConfigMaps: false as the ConfigMaps for certs are already generated in the same namespace.
   • certs.settings.addPeerValue: true Most important flag for adding a new Peer.
   • peer.gossipPeerAddress: <existing peer address> So that the new peer can gossip with existing peer.

   Refer to the fabric-peernode chart documentation for a complete list of available configuration options.

2. Install the fabric-peernode chart

   Ensure the Orderer tls certificate is in fabric-peernode/files

   # Get the orderer.crt from Kubernetes
   cd ./platforms/hyperledger-fabric/charts/fabric-peernode/files
   kubectl --namespace supplychain-net get configmap orderer-tls-cacert -o jsonpath='{.data.cacert}' > orderer.crt
   

   Execute the following command to install the Peer chart:

   cd ../..
   helm dependency update ./fabric-peernode
   helm install <release-name> ./fabric-peernode --namespace <namespace> --values <values-file.yaml>
   

   Replace the following placeholders:
   • <release-name>: The desired name for the Peer release.
   • <namespace>: The Kubernetes namespace where the Peer should be deployed.
   • <values-file.yaml>: The path to a YAML file containing the new peer configuration values.

3. Update the fabric-channel-join values.yaml file

   After the peer has started, we need to join the channel. The channel should already exist in the network. Following changes are must in the values.yaml file for a new peer to join an existing channel:

   • peer.name: <new peer name>
   • peer.type: general
   • peer.address: <new peer address>
   • peer.localMspId: <existing org MSP>
   • peer.channelName: <existing channel name>
   • peer.ordererAddress: <existing orderer grpc address> the Orderer Address to which the peer should connect.

   Refer to the fabric-channel-join chart documentation for a complete list of available configuration options.

4. Join the channel

   Execute the following command to join the channel:

   # From platforms/hyperledger-fabric/charts directory
   helm install <release-name> ./fabric-channel-join --namespace <namespace> --values <values-file.yaml>
   

   Replace the following placeholders:
   • <release-name>: The desired name for the join channel release.
   • <namespace>: The Kubernetes namespace must be same as the namespace of the Peer release.
   • <values-file.yaml>: The path to a YAML file containing the updated join channel configuration values.

Additional Notes

• The peerstatus is optional when the network is deployed for the first time but is mandatory for addition of new peer.

• Currently, only a general or non-anchor peer can be added.

• Chaincode Installation: Use the same network.yaml if you need to install chaincode on the new peers.

• With Fabric 2.2 and 2.5 chaincode lifecyle, re-installing chaincode on new peer is not needed as when the blocks are synced, the new peer will have access to already committed chaincode. If still needed, you can upgrade the version of the chaincode and install on all peers.

• Refer Install chaincode guide or Install external chaincode guide for details on installing chaincode.