github.com/sykesm/fabric@v1.1.0-preview.0.20200129034918-2aa12b1a0181/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 release. If you would like to use the previous lifecycle to 615 install and instantiate a chaincode, visit the v1.4 version of the 616 `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/