github.com/yacovm/fabric@v2.0.0-alpha.0.20191128145320-c5d4087dc723+incompatible/docs/source/channel_update_tutorial.rst (about)

     1  Adding an Org to a Channel
     2  ==========================
     3  
     4  .. note:: Ensure that you have downloaded the appropriate images and binaries
     5            as outlined in :doc:`install` and :doc:`prereqs` that conform to the
     6            version of this documentation (which can be found at the bottom of the
     7            table of contents to the left). In particular, your version of the
     8            ``fabric-samples`` folder must include the ``eyfn.sh`` ("Extending
     9            Your First Network") script and its related scripts.
    10  
    11  This tutorial serves as an extension to the :doc:`build_network` (BYFN) tutorial,
    12  and will demonstrate the addition of a new organization -- ``Org3`` -- to the
    13  application channel (``mychannel``) autogenerated by BYFN. It assumes a strong
    14  understanding of BYFN, including the usage and functionality of the aforementioned
    15  utilities.
    16  
    17  While we will focus solely on the integration of a new organization here, the same
    18  approach can be adopted when performing other channel configuration updates (updating
    19  modification policies or altering batch size, for example). To learn more about the
    20  process and possibilities of channel config updates in general, check out
    21  :doc:`config_update`). It's also worth noting that channel configuration updates like
    22  the one demonstrated here will usually be the responsibility of an organization admin
    23  (rather than a chaincode or application developer).
    24  
    25  .. note:: Make sure the automated ``byfn.sh`` script runs without error on
    26            your machine before continuing. If you have exported your binaries and
    27            the related tools (``cryptogen``, ``configtxgen``, etc) into your PATH
    28            variable, you'll be able to modify the commands accordingly without
    29            passing the fully qualified path.
    30  
    31  Setup the Environment
    32  ~~~~~~~~~~~~~~~~~~~~~
    33  
    34  We will be operating from the root of the ``first-network`` subdirectory within
    35  your local clone of ``fabric-samples``. Change into that directory now. You will
    36  also want to open a few extra terminals for ease of use.
    37  
    38  First, use the ``byfn.sh`` script to tidy up. This command will kill any active
    39  or stale docker containers and remove previously generated artifacts. It is by no
    40  means **necessary** to bring down a Fabric network in order to perform channel
    41  configuration update tasks. However, for the sake of this tutorial, we want to operate
    42  from a known initial state. Therefore let's run the following command to clean up any
    43  previous environments:
    44  
    45  .. code:: bash
    46  
    47    ./byfn.sh down
    48  
    49  Now generate the default BYFN artifacts:
    50  
    51  .. code:: bash
    52  
    53    ./byfn.sh generate
    54  
    55  And launch the network making use of the scripted execution within the CLI container:
    56  
    57  .. code:: bash
    58  
    59    ./byfn.sh up
    60  
    61  Now that you have a clean version of BYFN running on your machine, you have two
    62  different paths you can pursue. First, we offer a fully commented script that will
    63  carry out a config transaction update to bring Org3 into the network.
    64  
    65  Also, we will show a "manual" version of the same process, showing each step
    66  and explaining what it accomplishes (since we show you how to bring down your
    67  network before this manual process, you could also run the script and then look at
    68  each step).
    69  
    70  Bring Org3 into the Channel with the Script
    71  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    72  
    73  You should be in ``first-network``. To use the script, simply issue the following:
    74  
    75  .. code:: bash
    76  
    77    ./eyfn.sh up
    78  
    79  The output here is well worth reading. You'll see the Org3 crypto material being
    80  added, the config update being created and signed, and then chaincode being installed
    81  to allow Org3 to execute ledger queries.
    82  
    83  If everything goes well, you'll get this message:
    84  
    85  .. code:: bash
    86  
    87    ========= All GOOD, EYFN test execution completed ===========
    88  
    89  ``eyfn.sh`` can be used with the same Node.js chaincode and database options
    90  as ``byfn.sh`` by issuing the following (instead of ``./byfn.sh up``):
    91  
    92  .. code:: bash
    93  
    94    ./byfn.sh up -c testchannel -s couchdb -l node
    95  
    96  And then:
    97  
    98  .. code:: bash
    99  
   100    ./eyfn.sh up -c testchannel -s couchdb -l node
   101  
   102  For those who want to take a closer look at this process, the rest of the doc will
   103  show you each command for making a channel update and what it does.
   104  
   105  Bring Org3 into the Channel Manually
   106  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   107  
   108  .. note:: The manual steps outlined below assume that the ``FABRIC_LOGGING_SPEC``
   109            in the ``cli`` and ``Org3cli`` containers is set to ``DEBUG``.
   110  
   111            For the ``cli`` container, you can set this by modifying the
   112            ``docker-compose-cli.yaml`` file in the ``first-network`` directory.
   113            e.g.
   114  
   115            .. code::
   116  
   117              cli:
   118                container_name: cli
   119                image: hyperledger/fabric-tools:$IMAGE_TAG
   120                tty: true
   121                stdin_open: true
   122                environment:
   123                  - GOPATH=/opt/gopath
   124                  - CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock
   125                  #- FABRIC_LOGGING_SPEC=INFO
   126                  - FABRIC_LOGGING_SPEC=DEBUG
   127  
   128            For the ``Org3cli`` container, you can set this by modifying the
   129            ``docker-compose-org3.yaml`` file in the ``first-network`` directory.
   130            e.g.
   131  
   132            .. code::
   133  
   134              Org3cli:
   135                container_name: Org3cli
   136                image: hyperledger/fabric-tools:$IMAGE_TAG
   137                tty: true
   138                stdin_open: true
   139                environment:
   140                  - GOPATH=/opt/gopath
   141                  - CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock
   142                  #- FABRIC_LOGGING_SPEC=INFO
   143                  - FABRIC_LOGGING_SPEC=DEBUG
   144  
   145  If you've used the ``eyfn.sh`` script, you'll need to bring your network down.
   146  This can be done by issuing:
   147  
   148  .. code:: bash
   149  
   150    ./eyfn.sh down
   151  
   152  This will bring down the network, delete all the containers and undo what we've
   153  done to add Org3.
   154  
   155  When the network is down, bring it back up again.
   156  
   157  .. code:: bash
   158  
   159    ./byfn.sh generate
   160  
   161  Then:
   162  
   163  .. code:: bash
   164  
   165    ./byfn.sh up
   166  
   167  This will bring your network back to the same state it was in before you executed
   168  the ``eyfn.sh`` script.
   169  
   170  Now we're ready to add Org3 manually. As a first step, we'll need to generate Org3's
   171  crypto material.
   172  
   173  Generate the Org3 Crypto Material
   174  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   175  
   176  In another terminal, change into the ``org3-artifacts`` subdirectory from
   177  ``first-network``.
   178  
   179  .. code:: bash
   180  
   181    cd org3-artifacts
   182  
   183  There are two ``yaml`` files of interest here: ``org3-crypto.yaml`` and ``configtx.yaml``.
   184  First, generate the crypto material for Org3:
   185  
   186  .. code:: bash
   187  
   188    ../../bin/cryptogen generate --config=./org3-crypto.yaml
   189  
   190  This command reads in our new crypto ``yaml`` file -- ``org3-crypto.yaml`` -- and
   191  leverages ``cryptogen`` to generate the keys and certificates for an Org3
   192  CA as well as two peers bound to this new Org. As with the BYFN implementation,
   193  this crypto material is put into a newly generated ``crypto-config`` folder
   194  within the present working directory (in our case, ``org3-artifacts``).
   195  
   196  Now use the ``configtxgen`` utility to print out the Org3-specific configuration
   197  material in JSON. We will preface the command by telling the tool to look in the
   198  current directory for the ``configtx.yaml`` file that it needs to ingest.
   199  
   200  .. code:: bash
   201  
   202      export FABRIC_CFG_PATH=$PWD && ../../bin/configtxgen -printOrg Org3MSP > ../channel-artifacts/org3.json
   203  
   204  The above command creates a JSON file -- ``org3.json`` -- and outputs it into the
   205  ``channel-artifacts`` subdirectory at the root of ``first-network``. This
   206  file contains the policy definitions for Org3, as well as three important certificates
   207  presented in base 64 format: the admin user certificate (which will be needed to act as
   208  the admin of Org3 later on), a CA root cert, and a TLS root cert. In an upcoming step we
   209  will append this JSON file to the channel configuration.
   210  
   211  Our final piece of housekeeping is to port the Orderer Org's MSP material into
   212  the Org3 ``crypto-config`` directory. In particular, we are concerned with the
   213  Orderer's TLS root cert, which will allow for secure communication between
   214  Org3 entities and the network's ordering node.
   215  
   216  .. code:: bash
   217  
   218    cd ../ && cp -r crypto-config/ordererOrganizations org3-artifacts/crypto-config/
   219  
   220  Now we're ready to update the channel configuration...
   221  
   222  Prepare the CLI Environment
   223  ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   224  
   225  The update process makes use of the configuration translator tool -- ``configtxlator``.
   226  This tool provides a stateless REST API independent of the SDK. Additionally it
   227  provides a CLI, to simplify configuration tasks in Fabric networks. The tool allows
   228  for the easy conversion between different equivalent data representations/formats
   229  (in this case, between protobufs and JSON). Additionally, the tool can compute a
   230  configuration update transaction based on the differences between two channel
   231  configurations.
   232  
   233  First, exec into the CLI container. Recall that this container has been
   234  mounted with the BYFN ``crypto-config`` library, giving us access to the MSP material
   235  for the two original peer organizations and the Orderer Org. The bootstrapped
   236  identity is the Org1 admin user, meaning that any steps where we want to act as
   237  Org2 will require the export of MSP-specific environment variables.
   238  
   239  .. code:: bash
   240  
   241    docker exec -it cli bash
   242  
   243  Export the ``ORDERER_CA`` and ``CHANNEL_NAME`` variables:
   244  
   245  .. code:: bash
   246  
   247    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  && export CHANNEL_NAME=mychannel
   248  
   249  Check to make sure the variables have been properly set:
   250  
   251  .. code:: bash
   252  
   253    echo $ORDERER_CA && echo $CHANNEL_NAME
   254  
   255  .. note:: If for any reason you need to restart the CLI container, you will also need to
   256            re-export the two environment variables -- ``ORDERER_CA`` and ``CHANNEL_NAME``.
   257  
   258  Fetch the Configuration
   259  ~~~~~~~~~~~~~~~~~~~~~~~
   260  
   261  Now we have a CLI container with our two key environment variables -- ``ORDERER_CA``
   262  and ``CHANNEL_NAME`` exported.  Let's go fetch the most recent config block for the
   263  channel -- ``mychannel``.
   264  
   265  The reason why we have to pull the latest version of the config is because channel
   266  config elements are versioned. Versioning is important for several reasons. It prevents
   267  config changes from being repeated or replayed (for instance, reverting to a channel config
   268  with old CRLs would represent a security risk). Also it helps ensure concurrency (if you
   269  want to remove an Org from your channel, for example, after a new Org has been added,
   270  versioning will help prevent you from removing both Orgs, instead of just the Org you want
   271  to remove).
   272  
   273  .. code:: bash
   274  
   275    peer channel fetch config config_block.pb -o orderer.example.com:7050 -c $CHANNEL_NAME --tls --cafile $ORDERER_CA
   276  
   277  This command saves the binary protobuf channel configuration block to
   278  ``config_block.pb``. Note that the choice of name and file extension is arbitrary.
   279  However, following a convention which identifies both the type of object being
   280  represented and its encoding (protobuf or JSON) is recommended.
   281  
   282  When you issued the ``peer channel fetch`` command, there was a decent amount of
   283  output in the terminal. The last line in the logs is of interest:
   284  
   285  .. code:: bash
   286  
   287    2017-11-07 17:17:57.383 UTC [channelCmd] readBlock -> DEBU 011 Received block: 2
   288  
   289  This is telling us that the most recent configuration block for ``mychannel`` is
   290  actually block 2, **NOT** the genesis block. By default, the ``peer channel fetch config``
   291  command returns the most **recent** configuration block for the targeted channel, which
   292  in this case is the third block. This is because the BYFN script defined anchor
   293  peers for our two organizations -- ``Org1`` and ``Org2`` -- in two separate channel update
   294  transactions.
   295  
   296  As a result, we have the following configuration sequence:
   297  
   298    * block 0: genesis block
   299    * block 1: Org1 anchor peer update
   300    * block 2: Org2 anchor peer update
   301  
   302  Convert the Configuration to JSON and Trim It Down
   303  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   304  
   305  Now we will make use of the ``configtxlator`` tool to decode this channel
   306  configuration block into JSON format (which can be read and modified by humans).
   307  We also must strip away all of the headers, metadata, creator signatures, and
   308  so on that are irrelevant to the change we want to make. We accomplish this by
   309  means of the ``jq`` tool:
   310  
   311  .. code:: bash
   312  
   313    configtxlator proto_decode --input config_block.pb --type common.Block | jq .data.data[0].payload.data.config > config.json
   314  
   315  This leaves us with a trimmed down JSON object -- ``config.json``, located in
   316  the ``fabric-samples`` folder inside ``first-network`` -- which
   317  will serve as the baseline for our config update.
   318  
   319  Take a moment to open this file inside your text editor of choice (or in your
   320  browser). Even after you're done with this tutorial, it will be worth studying it
   321  as it reveals the underlying configuration structure and the other kind of channel
   322  updates that can be made. We discuss them in more detail in :doc:`config_update`.
   323  
   324  Add the Org3 Crypto Material
   325  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   326  
   327  .. note:: The steps you've taken up to this point will be nearly identical no matter
   328            what kind of config update you're trying to make. We've chosen to add an
   329            org with this tutorial because it's one of the most complex channel
   330            configuration updates you can attempt.
   331  
   332  We'll use the ``jq`` tool once more to append the Org3 configuration definition
   333  -- ``org3.json`` -- to the channel's application groups field, and name the output
   334  -- ``modified_config.json``.
   335  
   336  .. code:: bash
   337  
   338    jq -s '.[0] * {"channel_group":{"groups":{"Application":{"groups": {"Org3MSP":.[1]}}}}}' config.json ./channel-artifacts/org3.json > modified_config.json
   339  
   340  Now, within the CLI container we have two JSON files of interest -- ``config.json``
   341  and ``modified_config.json``. The initial file contains only Org1 and Org2 material,
   342  whereas "modified" file contains all three Orgs. At this point it's simply
   343  a matter of re-encoding these two JSON files and calculating the delta.
   344  
   345  First, translate ``config.json`` back into a protobuf called ``config.pb``:
   346  
   347  .. code:: bash
   348  
   349    configtxlator proto_encode --input config.json --type common.Config --output config.pb
   350  
   351  Next, encode ``modified_config.json`` to ``modified_config.pb``:
   352  
   353  .. code:: bash
   354  
   355    configtxlator proto_encode --input modified_config.json --type common.Config --output modified_config.pb
   356  
   357  Now use ``configtxlator`` to calculate the delta between these two config
   358  protobufs. This command will output a new protobuf binary named ``org3_update.pb``:
   359  
   360  .. code:: bash
   361  
   362    configtxlator compute_update --channel_id $CHANNEL_NAME --original config.pb --updated modified_config.pb --output org3_update.pb
   363  
   364  This new proto -- ``org3_update.pb`` -- contains the Org3 definitions and high
   365  level pointers to the Org1 and Org2 material. We are able to forgo the extensive
   366  MSP material and modification policy information for Org1 and Org2 because this
   367  data is already present within the channel's genesis block. As such, we only need
   368  the delta between the two configurations.
   369  
   370  Before submitting the channel update, we need to perform a few final steps. First,
   371  let's decode this object into editable JSON format and call it ``org3_update.json``:
   372  
   373  .. code:: bash
   374  
   375    configtxlator proto_decode --input org3_update.pb --type common.ConfigUpdate | jq . > org3_update.json
   376  
   377  Now, we have a decoded update file -- ``org3_update.json`` -- that we need to wrap
   378  in an envelope message. This step will give us back the header field that we stripped away
   379  earlier. We'll name this file ``org3_update_in_envelope.json``:
   380  
   381  .. code:: bash
   382  
   383    echo '{"payload":{"header":{"channel_header":{"channel_id":"'$CHANNEL_NAME'", "type":2}},"data":{"config_update":'$(cat org3_update.json)'}}}' | jq . > org3_update_in_envelope.json
   384  
   385  Using our properly formed JSON -- ``org3_update_in_envelope.json`` -- we will
   386  leverage the ``configtxlator`` tool one last time and convert it into the
   387  fully fledged protobuf format that Fabric requires. We'll name our final update
   388  object ``org3_update_in_envelope.pb``:
   389  
   390  .. code:: bash
   391  
   392    configtxlator proto_encode --input org3_update_in_envelope.json --type common.Envelope --output org3_update_in_envelope.pb
   393  
   394  Sign and Submit the Config Update
   395  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   396  
   397  Almost done!
   398  
   399  We now have a protobuf binary -- ``org3_update_in_envelope.pb`` -- within
   400  our CLI container. However, we need signatures from the requisite Admin users
   401  before the config can be written to the ledger. The modification policy (mod_policy)
   402  for our channel Application group is set to the default of "MAJORITY", which means that
   403  we need a majority of existing org admins to sign it. Because we have only two orgs --
   404  Org1 and Org2 -- and the majority of two is two, we need both of them to sign. Without
   405  both signatures, the ordering service will reject the transaction for failing to
   406  fulfill the policy.
   407  
   408  First, let's sign this update proto as the Org1 Admin. Remember that the CLI container
   409  is bootstrapped with the Org1 MSP material, so we simply need to issue the
   410  ``peer channel signconfigtx`` command:
   411  
   412  .. code:: bash
   413  
   414    peer channel signconfigtx -f org3_update_in_envelope.pb
   415  
   416  The final step is to switch the CLI container's identity to reflect the Org2 Admin
   417  user. We do this by exporting four environment variables specific to the Org2 MSP.
   418  
   419  .. note:: Switching between organizations to sign a config transaction (or to do anything
   420            else) is not reflective of a real-world Fabric operation. A single container
   421            would never be mounted with an entire network's crypto material. Rather, the
   422            config update would need to be securely passed out-of-band to an Org2
   423            Admin for inspection and approval.
   424  
   425  Export the Org2 environment variables:
   426  
   427  .. code:: bash
   428  
   429    # you can issue all of these commands at once
   430  
   431    export CORE_PEER_LOCALMSPID="Org2MSP"
   432  
   433    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
   434  
   435    export CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp
   436  
   437    export CORE_PEER_ADDRESS=peer0.org2.example.com:9051
   438  
   439  Lastly, we will issue the ``peer channel update`` command. The Org2 Admin signature
   440  will be attached to this call so there is no need to manually sign the protobuf a
   441  second time:
   442  
   443  .. note:: The upcoming update call to the ordering service will undergo a series
   444            of systematic signature and policy checks. As such you may find it
   445            useful to stream and inspect the ordering node's logs. From another shell,
   446            issue a ``docker logs -f orderer.example.com`` command to display them.
   447  
   448  Send the update call:
   449  
   450  .. code:: bash
   451  
   452    peer channel update -f org3_update_in_envelope.pb -c $CHANNEL_NAME -o orderer.example.com:7050 --tls --cafile $ORDERER_CA
   453  
   454  You should see a message digest indication similar to the following if your
   455  update has been submitted successfully:
   456  
   457  .. code:: bash
   458  
   459    2018-02-24 18:56:33.499 UTC [msp/identity] Sign -> DEBU 00f Sign: digest: 3207B24E40DE2FAB87A2E42BC004FEAA1E6FDCA42977CB78C64F05A88E556ABA
   460  
   461  You will also see the submission of our configuration transaction:
   462  
   463  .. code:: bash
   464  
   465    2018-02-24 18:56:33.499 UTC [channelCmd] update -> INFO 010 Successfully submitted channel update
   466  
   467  The successful channel update call returns a new block -- block 5 -- to all of the
   468  peers on the channel. If you remember, blocks 0-2 are the initial channel
   469  configurations while blocks 3 and 4 are the instantiation and invocation of
   470  the ``mycc`` chaincode. As such, block 5 serves as the most recent channel
   471  configuration with Org3 now defined on the channel.
   472  
   473  Inspect the logs for ``peer0.org1.example.com``:
   474  
   475  .. code:: bash
   476  
   477        docker logs -f peer0.org1.example.com
   478  
   479  Follow the demonstrated process to fetch and decode the new config block if you wish to inspect
   480  its contents.
   481  
   482  Configuring Leader Election
   483  ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   484  
   485  .. note:: This section is included as a general reference for understanding
   486            the leader election settings when adding organizations to a network
   487            after the initial channel configuration has completed. This sample
   488            defaults to dynamic leader election, which is set for all peers in the
   489            network in `peer-base.yaml`.
   490  
   491  Newly joining peers are bootstrapped with the genesis block, which does not
   492  contain information about the organization that is being added in the channel
   493  configuration update. Therefore new peers are not able to utilize gossip as
   494  they cannot verify blocks forwarded by other peers from their own organization
   495  until they get the configuration transaction which added the organization to the
   496  channel. Newly added peers must therefore have one of the following
   497  configurations so that they receive blocks from the ordering service:
   498  
   499  1. To utilize static leader mode, configure the peer to be an organization
   500  leader:
   501  
   502  ::
   503  
   504      CORE_PEER_GOSSIP_USELEADERELECTION=false
   505      CORE_PEER_GOSSIP_ORGLEADER=true
   506  
   507  
   508  .. note:: This configuration must be the same for all new peers added to the
   509            channel.
   510  
   511  2. To utilize dynamic leader election, configure the peer to use leader
   512  election:
   513  
   514  ::
   515  
   516      CORE_PEER_GOSSIP_USELEADERELECTION=true
   517      CORE_PEER_GOSSIP_ORGLEADER=false
   518  
   519  
   520  .. note:: Because peers of the newly added organization won't be able to form
   521            membership view, this option will be similar to the static
   522            configuration, as each peer will start proclaiming itself to be a
   523            leader. However, once they get updated with the configuration
   524            transaction that adds the organization to the channel, there will be
   525            only one active leader for the organization. Therefore, it is
   526            recommended to leverage this option if you eventually want the
   527            organization's peers to utilize leader election.
   528  
   529  
   530  Join Org3 to the Channel
   531  ~~~~~~~~~~~~~~~~~~~~~~~~
   532  
   533  At this point, the channel configuration has been updated to include our new
   534  organization -- ``Org3`` -- meaning that peers attached to it can now join ``mychannel``.
   535  
   536  First, let's launch the containers for the Org3 peers and an Org3-specific CLI.
   537  
   538  Open a new terminal and from ``first-network`` kick off the Org3 docker compose:
   539  
   540  .. code:: bash
   541  
   542    docker-compose -f docker-compose-org3.yaml up -d
   543  
   544  This new compose file has been configured to bridge across our initial network,
   545  so the two peers and the CLI container will be able to resolve with the existing
   546  peers and ordering node. With the three new containers now running, exec into
   547  the Org3-specific CLI container:
   548  
   549  .. code:: bash
   550  
   551    docker exec -it Org3cli bash
   552  
   553  Just as we did with the initial CLI container, export the two key environment
   554  variables: ``ORDERER_CA`` and ``CHANNEL_NAME``:
   555  
   556  .. code:: bash
   557  
   558    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 && export CHANNEL_NAME=mychannel
   559  
   560  Check to make sure the variables have been properly set:
   561  
   562  .. code:: bash
   563  
   564    echo $ORDERER_CA && echo $CHANNEL_NAME
   565  
   566  Now let's send a call to the ordering service asking for the genesis block of
   567  ``mychannel``. The ordering service is able to verify the Org3 signature
   568  attached to this call as a result of our successful channel update. If Org3
   569  has not been successfully appended to the channel config, the ordering
   570  service should reject this request.
   571  
   572  .. note:: Again, you may find it useful to stream the ordering node's logs
   573            to reveal the sign/verify logic and policy checks.
   574  
   575  Use the ``peer channel fetch`` command to retrieve this block:
   576  
   577  .. code:: bash
   578  
   579    peer channel fetch 0 mychannel.block -o orderer.example.com:7050 -c $CHANNEL_NAME --tls --cafile $ORDERER_CA
   580  
   581  Notice, that we are passing a ``0`` to indicate that we want the first block on
   582  the channel's ledger (i.e. the genesis block). If we simply passed the
   583  ``peer channel fetch config`` command, then we would have received block 5 -- the
   584  updated config with Org3 defined. However, we can't begin our ledger with a
   585  downstream block -- we must start with block 0.
   586  
   587  Issue the ``peer channel join`` command and pass in the genesis block -- ``mychannel.block``:
   588  
   589  .. code:: bash
   590  
   591    peer channel join -b mychannel.block
   592  
   593  If you want to join the second peer for Org3, export the ``TLS`` and ``ADDRESS`` variables
   594  and reissue the ``peer channel join command``:
   595  
   596  .. code:: bash
   597  
   598    export CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org3.example.com/peers/peer1.org3.example.com/tls/ca.crt && export CORE_PEER_ADDRESS=peer1.org3.example.com:12051
   599  
   600    peer channel join -b mychannel.block
   601  
   602  .. _upgrade-and-invoke:
   603  
   604  Install, define, and invoke chaincode
   605  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   606  
   607  Once you have joined the channel, you can package and install a chaincode on a
   608  peer of Org3. You then need to approve the chaincode definition as org3.
   609  Because the chaincode definition has already been committed to the channel
   610  you have joined, you can start using the chaincode after you approve the
   611  definition.
   612  
   613  .. note:: These instructions use the Fabric chaincode lifecycle introduced in
   614            the v2.0 Alpha release. If you would like to use the previous
   615            lifecycle to install and instantiate a chaincode, visit the v1.4
   616            version of the `Adding an org to a channel tutorial <https://hyperledger-fabric.readthedocs.io/en/release-1.4/channel_update_tutorial.html>`__.
   617  
   618  The first step is to package the chaincode from the Org3 CLI:
   619  
   620  .. code:: bash
   621  
   622      peer lifecycle chaincode package mycc.tar.gz --path github.com/hyperledger/fabric-samples/chaincode/abstore/go/ --lang golang --label mycc_1
   623  
   624  This command will create a chaincode package named ``mycc.tar.gz``, which we can
   625  use to install the chaincode on our peer. In this command, you need to provide a
   626  chaincode package label as a description of the chaincode. Modify the command
   627  accordingly if the channel is running a chaincode written in Java or Node.js.
   628  Issue the following command to install the package on peer0 of Org3:
   629  
   630  .. code:: bash
   631  
   632      # this command installs a chaincode package on your peer
   633      peer lifecycle chaincode install mycc.tar.gz
   634  
   635  You can also modify the environment variables and reissue the command if you
   636  want to install the chaincode on the second peer of Org3. Note that a second
   637  installation is not mandated, as you only need to install chaincode on peers
   638  that are going to serve as endorsers or otherwise interface with the ledger
   639  (i.e. query only). Peers will still run the validation logic and serve as
   640  committers without a running chaincode container.
   641  
   642  The next step is to approve the chaincode definition of ``mycc`` as Org3. Org3
   643  needs to approve the same definition that Org1 and Org2 approved and committed
   644  to the channel. The chaincode definition also needs to include the chaincode
   645  package identifier. You can find the package identifier by querying your peer:
   646  
   647  .. code:: bash
   648  
   649      # this returns the details of the packages installed on your peers
   650      peer lifecycle chaincode queryinstalled
   651  
   652  You should see output similar to the following:
   653  
   654  .. code:: bash
   655  
   656        Get installed chaincodes on peer:
   657        Package ID: mycc_1:3a8c52d70c36313cfebbaf09d8616e7a6318ababa01c7cbe40603c373bcfe173, Label: mycc_1
   658  
   659  We are going to need the package ID in a future command, so lets go ahead and
   660  save it as an environment variable. Paste the package ID returned by the
   661  `peer lifecycle chaincode queryinstalled` into the command below. The package ID
   662  may not be the same for all users, so you need to complete this step using the
   663  package ID returned from your console.
   664  
   665  .. code:: bash
   666  
   667     # Save the package ID as an environment variable.
   668  
   669     CC_PACKAGE_ID=mycc_1:3a8c52d70c36313cfebbaf09d8616e7a6318ababa01c7cbe40603c373bcfe173
   670  
   671  Use the following command to approve a definition of the  ``mycc`` chaincode
   672  for Org3:
   673  
   674  .. code:: bash
   675  
   676      # this approves a chaincode definition for your org
   677      # use the --package-id flag to provide the package identifier
   678      # use the --init-required flag to request the ``Init`` function be invoked to initialize the chaincode
   679      peer lifecycle chaincode approveformyorg --channelID $CHANNEL_NAME --name mycc --version 1.0 --init-required --package-id $CC_PACKAGE_ID --sequence 1 --tls true --cafile /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem --waitForEvent
   680  
   681  You can use the ``peer lifecycle chaincode querycommitted`` command to check if
   682  the chaincode definition you have approved has already been committed to the
   683  channel.
   684  
   685  .. code:: bash
   686  
   687      # use the --name flag to select the chaincode whose definition you want to query
   688      peer lifecycle chaincode querycommitted --channelID $CHANNEL_NAME --name mycc --cafile /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem
   689  
   690  A successful command will return information about the committed definition:
   691  
   692  .. code:: bash
   693  
   694      Committed chaincode definition for chaincode 'mycc' on channel 'mychannel':
   695      Version: 1, Sequence: 1, Endorsement Plugin: escc, Validation Plugin: vscc
   696  
   697  Since the chaincode definition has already been committed, you are ready to use
   698  the ``mycc`` chaincode after you approve the definition. The chaincode definition
   699  uses the default endorsement policy, which requires a majority of organizations
   700  on the channel endorse a transaction. This implies that if an organization is
   701  added to or removed from the channel, the endorsement policy is updated
   702  automatically. We previously needed endorsements from Org1 and Org2 (2 out of 2).
   703  Now we need endorsements from two organizations out of Org1, Org2, and Org3 (2
   704  out of 3).
   705  
   706  Query the chaincode to ensure that it has started. Note that you may need to
   707  wait for the chaincode container to start.
   708  
   709  .. code:: bash
   710  
   711      peer chaincode query -C $CHANNEL_NAME -n mycc -c '{"Args":["query","a"]}'
   712  
   713  We should see a response of ``Query Result: 90``.
   714  
   715  Now issue an invocation to move ``10`` from ``a`` to ``b``. In the command
   716  below, we target a peer in Org1 and Org3 to collect a sufficient number of
   717  endorsements.
   718  
   719  .. code:: bash
   720  
   721      peer chaincode invoke -o orderer.example.com:7050  --tls $CORE_PEER_TLS_ENABLED --cafile $ORDERER_CA -C $CHANNEL_NAME -n mycc -c '{"Args":["invoke","a","b","10"]}' --peerAddresses peer0.org1.example.com:7051 --tlsRootCertFiles /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt --peerAddresses peer0.org3.example.com:11051 --tlsRootCertFiles /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org3.example.com/peers/peer0.org3.example.com/tls/ca.crt
   722  
   723  Query one final time:
   724  
   725  .. code:: bash
   726  
   727      peer chaincode query -C $CHANNEL_NAME -n mycc -c '{"Args":["query","a"]}'
   728  
   729  We should see a response of ``Query Result: 80``, accurately reflecting the
   730  update of this chaincode's world state.
   731  
   732  Conclusion
   733  ~~~~~~~~~~
   734  
   735  The channel configuration update process is indeed quite involved, but there is a
   736  logical method to the various steps. The endgame is to form a delta transaction object
   737  represented in protobuf binary format and then acquire the requisite number of admin
   738  signatures such that the channel configuration update transaction fulfills the channel's
   739  modification policy.
   740  
   741  The ``configtxlator`` and ``jq`` tools, along with the ever-growing ``peer channel``
   742  commands, provide us with the functionality to accomplish this task.
   743  
   744  Updating the Channel Config to include an Org3 Anchor Peer (Optional)
   745  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   746  
   747  The Org3 peers were able to establish gossip connection to the Org1 and Org2
   748  peers since Org1 and Org2 had anchor peers defined in the channel configuration.
   749  Likewise newly added organizations like Org3 should also define their anchor peers
   750  in the channel configuration so that any new peers from other organizations can
   751  directly discover an Org3 peer.
   752  
   753  Continuing from the Org3 CLI, we will make a channel configuration update to
   754  define an Org3 anchor peer. The process will be similar to the previous
   755  configuration update, therefore we'll go faster this time.
   756  
   757  As before, we will fetch the latest channel configuration to get started.
   758  Inside the CLI container for Org3 fetch the most recent config block for the channel,
   759  using the ``peer channel fetch`` command.
   760  
   761  .. code:: bash
   762  
   763    peer channel fetch config config_block.pb -o orderer.example.com:7050 -c $CHANNEL_NAME --tls --cafile $ORDERER_CA
   764  
   765  After fetching the config block we will want to convert it into JSON format. To do
   766  this we will use the configtxlator tool, as done previously when adding Org3 to the
   767  channel. When converting it we need to remove all the headers, metadata, and signatures
   768  that are not required to update Org3 to include an anchor peer by using the jq
   769  tool. This information will be reincorporated later before we proceed to update the
   770  channel configuration.
   771  
   772  .. code:: bash
   773  
   774      configtxlator proto_decode --input config_block.pb --type common.Block | jq .data.data[0].payload.data.config > config.json
   775  
   776  The ``config.json`` is the now trimmed JSON representing the latest channel configuration
   777  that we will update.
   778  
   779  Using the jq tool again, we will update the configuration JSON with the Org3 anchor peer we
   780  want to add.
   781  
   782  .. code:: bash
   783  
   784      jq '.channel_group.groups.Application.groups.Org3MSP.values += {"AnchorPeers":{"mod_policy": "Admins","value":{"anchor_peers": [{"host": "peer0.org3.example.com","port": 11051}]},"version": "0"}}' config.json > modified_anchor_config.json
   785  
   786  We now have two JSON files, one for the current channel configuration,
   787  ``config.json``, and one for the desired channel configuration ``modified_anchor_config.json``.
   788  Next we convert each of these back into protobuf format and calculate the delta between the two.
   789  
   790  Translate ``config.json`` back into protobuf format as ``config.pb``
   791  
   792  .. code:: bash
   793  
   794      configtxlator proto_encode --input config.json --type common.Config --output config.pb
   795  
   796  Translate the ``modified_anchor_config.json`` into protobuf format as ``modified_anchor_config.pb``
   797  
   798  .. code:: bash
   799  
   800      configtxlator proto_encode --input modified_anchor_config.json --type common.Config --output modified_anchor_config.pb
   801  
   802  Calculate the delta between the two protobuf formatted configurations.
   803  
   804  .. code:: bash
   805  
   806      configtxlator compute_update --channel_id $CHANNEL_NAME --original config.pb --updated modified_anchor_config.pb --output anchor_update.pb
   807  
   808  Now that we have the desired update to the channel we must wrap it in an envelope
   809  message so that it can be properly read. To do this we must first convert the protobuf
   810  back into a JSON that can be wrapped.
   811  
   812  We will use the configtxlator command again to convert ``anchor_update.pb`` into ``anchor_update.json``
   813  
   814  .. code:: bash
   815  
   816      configtxlator proto_decode --input anchor_update.pb --type common.ConfigUpdate | jq . > anchor_update.json
   817  
   818  Next we will wrap the update in an envelope message, restoring the previously
   819  stripped away header, outputting it to ``anchor_update_in_envelope.json``
   820  
   821  .. code:: bash
   822  
   823      echo '{"payload":{"header":{"channel_header":{"channel_id":"'$CHANNEL_NAME'", "type":2}},"data":{"config_update":'$(cat anchor_update.json)'}}}' | jq . > anchor_update_in_envelope.json
   824  
   825  Now that we have reincorporated the envelope we need to convert it
   826  to a protobuf so it can be properly signed and submitted to the orderer for the update.
   827  
   828  .. code:: bash
   829  
   830      configtxlator proto_encode --input anchor_update_in_envelope.json --type common.Envelope --output anchor_update_in_envelope.pb
   831  
   832  Now that the update has been properly formatted it is time to sign off and submit it. Since this
   833  is only an update to Org3 we only need to have Org3 sign off on the update. As we are
   834  in the Org3 CLI container there is no need to switch the CLI containers identity, as it is
   835  already using the Org3 identity. Therefore we can just use the ``peer channel update`` command
   836  as it will also sign off on the update as the Org3 admin before submitting it to the orderer.
   837  
   838  .. code:: bash
   839  
   840      peer channel update -f anchor_update_in_envelope.pb -c $CHANNEL_NAME -o orderer.example.com:7050 --tls --cafile $ORDERER_CA
   841  
   842  The orderer receives the config update request and cuts a block with the updated configuration.
   843  As peers receive the block, they will process the configuration updates.
   844  
   845  Inspect the logs for one of the peers. While processing the configuration transaction from the new block,
   846  you will see gossip re-establish connections using the new anchor peer for Org3. This is proof
   847  that the configuration update has been successfully applied!
   848  
   849  .. code:: bash
   850  
   851      docker logs -f peer0.org1.example.com
   852  
   853  .. code:: bash
   854  
   855      2019-06-12 17:08:57.924 UTC [gossip.gossip] learnAnchorPeers -> INFO 89a Learning about the configured anchor peers of Org1MSP for channel mychannel : [{peer0.org1.example.com 7051}]
   856      2019-06-12 17:08:57.926 UTC [gossip.gossip] learnAnchorPeers -> INFO 89b Learning about the configured anchor peers of Org2MSP for channel mychannel : [{peer0.org2.example.com 9051}]
   857      2019-06-12 17:08:57.926 UTC [gossip.gossip] learnAnchorPeers -> INFO 89c Learning about the configured anchor peers of Org3MSP for channel mychannel : [{peer0.org3.example.com 11051}]
   858  
   859  Congratulations, you have now made two configuration updates --- one to add Org3 to the channel,
   860  and a second to define an anchor peer for Org3.
   861  
   862  .. Licensed under Creative Commons Attribution 4.0 International License
   863     https://creativecommons.org/licenses/by/4.0/