From 58a385796dc176acc96f4d0787d94b4d9ea1251c Mon Sep 17 00:00:00 2001 From: Jason Yellick Date: Fri, 9 Feb 2018 14:17:45 -0500 Subject: [PATCH] [FAB-8186] BYFN reconfig to use configtxlator cli The BYFN reconfig tutorial currently uses curl commands to access the configtxlator server REST APIs. This is no longer necessary and complicates the tutorial unnecessarily. This CR switches them to use the new CLI option. Change-Id: Id31bdce50266fa16aa4a533c41d5f2433dfd16dc Signed-off-by: Jason Yellick --- docs/source/channel_update.rst | 79 ++++++++++++---------------------- 1 file changed, 27 insertions(+), 52 deletions(-) diff --git a/docs/source/channel_update.rst b/docs/source/channel_update.rst index af6580b2290..bb703b76d53 100644 --- a/docs/source/channel_update.rst +++ b/docs/source/channel_update.rst @@ -103,12 +103,12 @@ Org3 entities and the network's ordering node. Now we're ready to reconfigure... -Start the ``configtxlator`` server -================================== +Prepare the CLI Environment +=========================== The update process makes use of the configuration translator tool - ``configtxlator``. -This tool provides a true stateless REST API, independent of the -SDK, to simplify configuration tasks in Hyperledger Fabric blockchain networks. +This tool provides a true stateless REST API, independent of the SDK, as well as a CLI, +to simplify configuration tasks in Hyperledger Fabric blockchain networks. The tool converts easily between different equivalent data representations/formats. For example, in one mode of tool operation, the tool performs conversions between the binary protobuf format to a human-readable JSON textual format, and vice-versa. @@ -161,20 +161,6 @@ with JSON objects returned by the ``configtxlator`` tool: apt update && apt install jq -Start the ``configtxlator`` REST server: - -.. code:: bash - - # Press enter twice - - configtxlator start & - -Set the URL: - -.. code:: bash - - CONFIGTXLATOR_URL=http://127.0.0.1:7059 - Export the ``ORDERER_CA`` and ``CHANNEL_NAME`` variables: .. code:: bash @@ -187,17 +173,17 @@ Check to make sure the variables have been properly set: echo $ORDERER_CA && echo $CHANNEL_NAME -.. note:: If for any reason you need to restart the CLI container, you will also - need to restart the REST server and export the three environment - variables - ``CONFIGTXLATOR_URL``, ``ORDERER_CA`` and ``CHANNEL_NAME``. + +.. note:: If for any reason you need to restart the CLI container, you will also need to + re-export the two environment variables - ``ORDERER_CA`` and ``CHANNEL_NAME``. The jq installation will persist, you need not install it a second time. Form the update objects & reconfigure the channel ================================================= -Now we have a running REST server within the CLI container and we have exported -our two key environment variables - ``ORDERER_CA`` & ``CHANNEL_NAME``. Let's go -fetch the most recent config block for the channel - ``mychannel``. +Now we have a CLI container with our two key environment variables - ``ORDERER_CA`` +& ``CHANNEL_NAME`` exported. Let's go fetch the most recent config block for the +channel - ``mychannel``. .. code:: bash @@ -224,27 +210,16 @@ our two organizations - ``Org1`` & ``Org2`` - were defined by means of two separate channel update transactions. As such, we have the following configuration sequence: block 0 - genesis; block 1 - Org1 anchor peer update; block 2 - Org2 anchor peer update. -Now we will make use of the ``configtxlator`` server and decode this channel -configuration block into human-readable and editable JSON format. - -.. code:: bash - - curl -X POST --data-binary @config_block.pb "$CONFIGTXLATOR_URL/protolator/decode/common.Block" | jq . > config_block.json - -We are naming the decoded output - ``config_block.json``. (Again, you are free -to apply your own naming conventions throughout these steps.) If you issue an ``ls`` -within the CLI container, you should see our two objects: the binary protobuf -channel configuration - ``config_block.pb`` - and the JSON representation of -this object - ``config_block.json``. - -Now we need to scope the ``config_block.json`` object and strip away all of the -encapsulating wrappers. We are not concerned with the headers, metadata, -creator signature, etc., but, rather, only with the configuration definition inside the -transaction. We accomplish this by means of the ``jq`` tool: +Now we will make use of the ``configtxlator`` tool to decode this channel +configuration block into human-readable and editable JSON format. We also +filter the output object and strip away all of the encapsulating wrappers. +We are not concerned with the headers, metadata, creator signature, etc., but, +rather, only with the configuration definition inside the transaction. We +accomplish this by means of the ``jq`` tool: .. code:: bash - jq .data.data[0].payload.data.config config_block.json > config.json + configtxlator proto_decode --input config_block.pb --type common.Block | jq .data.data[0].payload.data.config config_block.json > config.json This leaves us with a trimmed down JSON object - ``config.json`` - which will serve as the baseline for our config update. We'll use the ``jq`` tool once @@ -253,11 +228,11 @@ application groups field, and name the output - ``updated_config.json``. .. code:: bash - jq -s '.[0] * {"channel_group":{"groups":{"Application":{"groups": {"Org3MSP":.[1]}}}}}' config.json ./channel-artifacts/org3.json >& updated_config.json + jq -s '.[0] * {"channel_group":{"groups":{"Application":{"groups": {"Org3MSP":.[1]}}}}}' config.json ./channel-artifacts/org3.json > modified_config.json Now, within the CLI container we have two JSON files of interest - ``config.json`` -& ``updated_config.json``. The initial file contains only Org1 and Org2 material, -whereas the aptly named "updated config" file contains all three Orgs. At this +& ``modified_config.json``. The initial file contains only Org1 and Org2 material, +whereas the aptly named "modified config" file contains all three Orgs. At this point it's simply a matter of re-encoding these two JSON files and calculating the delta. @@ -265,20 +240,20 @@ First, encode ``config.json`` to ``config.pb``: .. code:: bash - curl -X POST --data-binary @config.json "$CONFIGTXLATOR_URL/protolator/encode/common.Config" > config.pb + configtxlator proto_encode --input config.json --type common.Config --output config.pb -Next, encode ``updated_config.json`` to ``updated_config.pb``: +Next, encode ``modified_config.json`` to ``modified_config.pb``: .. code:: bash - curl -X POST --data-binary @updated_config.json "$CONFIGTXLATOR_URL/protolator/encode/common.Config" > updated_config.pb + configtxlator proto_encode --input modified_config.json --type common.Config --output modified_config.pb -Now use the ``configtxlator`` server to calculate the delta between these two +Now use ``configtxlator`` to calculate the delta between these two config protos. This command will output a new protobuf binary named - ``org3_update.pb``: .. code:: bash - curl -X POST -F channel=$CHANNEL_NAME -F "original=@config.pb" -F "updated=@updated_config.pb" "${CONFIGTXLATOR_URL}/configtxlator/compute/update-from-configs" > org3_update.pb + configtxlator compute_update --channel_id $CHANNEL_NAME --original config.pb --updated modified_config.pb --output org3_update.pb This new proto - ``org3_update.pb`` - contains the Org3 definitions and high level pointers to the Org1 and Org2 material. We are able to forgo the extensive MSP material and modification @@ -291,7 +266,7 @@ let's decode this object into editable JSON format and call it ``org3_update.jso .. code:: bash - curl -X POST --data-binary @org3_update.pb "$CONFIGTXLATOR_URL/protolator/decode/common.ConfigUpdate" | jq . > org3_update.json + configtxlator proto_decode --input org3_update.pb --type common.ConfigUpdate | jq . > org3_update.json Now, we have a decoded update file - ``org3_update.json`` - that we need to wrap in an envelope message. This step will give us back the header field that we stripped away @@ -308,7 +283,7 @@ object - ``org3_update_in_envelope.pb``: .. code:: bash - curl -X POST --data-binary @org3_update_in_envelope.json "$CONFIGTXLATOR_URL/protolator/encode/common.Envelope" > org3_update_in_envelope.pb + configtxlator proto_encode --input org3_update_in_envelope.json --type common.Envelope --output org3_update_in_envelope.pb Almost done! We now have a protobuf binary - ``org3_update_in_envelope.pb`` - within our CLI container, however we need signatures from the requisite Admin users