Orderer deploy guide edits for participation API #2148
Conversation
joealewine
force-pushed
the
partorderer
branch
3 times, most recently
from
85a8ef5
to
82b01a9
Compare
| @@ -175,7 +178,7 @@ Note: while it is possible to add additional nodes to an ordering service, only | |||
|
|
|||
| If you’ve read through the key concept topic on :doc:`orderer/ordering_service`, you should have a good idea of the role the ordering service plays in a network and the nature of its interactions with other network components. The ordering service is responsible for literally “ordering” endorsed transactions into blocks, which peers then validate and commit to their ledgers. | |||
|
|
|||
| These roles are important to understand before you create an ordering service, as it will influence your customization and deployment decisions. Among the chief differences between a peer and ordering service is that in a production network, multiple ordering nodes work together to form the “ordering service” of a channel. This creates a series of important decisions that need to be made at both the node level and at the cluster level. Some of these cluster decisions are not made in individual ordering node ``orderer.yaml`` files but instead in the ``configtx.yaml`` file that is used to generate the genesis block for the system channel (which is used to bootstrap ordering nodes), and also used to generate the genesis block of application channels. For a look at the various decisions you will need to make, check out :doc:`deployorderer/ordererplan`. | |||
| These roles are important to understand before you create an ordering service, as it will influence your customization and deployment decisions. Among the chief differences between a peer and ordering service is that in a production network, multiple ordering nodes work together to form the “ordering service” of a channel (these nodes are also known as the “consenter set”). This creates a series of important decisions that need to be made at both the node level and at the cluster level. Some of these cluster decisions are not made in individual ordering node ``orderer.yaml`` files but instead in the ``configtx.yaml`` file that is used to generate the genesis block for an application channel. For a look at the various decisions you will need to make, check out :doc:`deployorderer/ordererplan`. | |||
There was a problem hiding this comment.
file that is used to generate the genesis block for an application channel.
Should we just say
file that is used to generate the genesis block for a channel.
There was a problem hiding this comment.
I left this as "application channel" because of the section above where I distinguished between the system channel and application channels. When we've deprecated the system channel more fully we can go back and remove this, imo.
|
|
||
| * **`Enabled`**: If you are bootstrapping the ordering node with a system channel genesis block, this should remain `false`. If you are **not** bootstrapping the ordering node with a system channel genesis block, this should be overridden to `true`. Make sure that your [`General.BoostrapMethod`](#general-boostrapmethod) is set to `none` if `ChannelParticipation.Enabled` is set to `true`, otherwise you will get an error when you attempt to start the node. | ||
| * **`MaxRequestBodySize`**: (default value should not be overridden) This value controls the maximum size a configuration block can be and be accepted by this ordering node. Most configuration blocks are smaller than 1 MB, but if for some reason a configuration block is too large to be accept, bring down the node, increase this value, and restart the node. | ||
|
|
There was a problem hiding this comment.
We are missing the new Admin* section which is used to define the orderer admin endpoint. See https://hyperledger-fabric.readthedocs.io/en/latest/create_channel/create_channel_participation.html#configure-the-orderer-yaml-file-for-each-orderer for the list of parameters.
There was a problem hiding this comment.
Ah, yes. I forgot that had been added! Thank you.
| INFO 01e raft.node: 1 elected leader 2 at term 11 channel=syschannel node=1 | ||
| INFO 01f Raft leader changed: 0 -> 2 channel=syschannel node=1 | ||
| ``` | ||
| You have successfully started one node, you now need to repeat these steps to configure and start the other two orderers. When a majority of orderers are started, a Raft leader is elected. |
There was a problem hiding this comment.
We need to tell them what to look for in the logs to know they are successful. I know this repeats what is in the channel participation api tutorial...
INFO 01d Registrar initializing without a system channel, number of application channels: 0, with 0 consensus.Chain(s) and 0 follower.Chain(s)
INFO 01f Starting orderer:
There was a problem hiding this comment.
I added this to the above section where I had left the response you get when starting a node. Also I deleted this section starting with "when a majority" since I assume this isn't true until the nodes are actually joined to a channel.
| ### Creating profiles for application channels | ||
|
|
||
| Both the system and all application channels are built using a `configtx.yaml` file. Therefore, when editing your `configtx.yaml` to create the genesis block for your system channel, you can also add profiles for any application channels that will be created on this network. However, note that while you can define any set of consenters for each channel, **every consenter added to an application channel must first be a part of the system channel**. You cannot specify a consenter that is not a part of the system channel. Also, it is not possible to control the leader of the consenter set. Leaders are chosen by the `etcdraft` protocol used by the ordering nodes. | ||
|
|
||
| ## Sizing your ordering node resources | ||
|
|
||
| Because ordering nodes do not host a state database or chaincode, an ordering node will typically only have a single container associated with it. Like the “peer container” associated with the peer, this container encapsulates the ordering process that orders transactions into blocks for all channels on which the ordering node is a consenter (ordering nodes also validate actions in particular cases). The ordering node storage includes the blockchain for all of channels on which the node is a consenter. |
There was a problem hiding this comment.
The ordering node storage includes the blockchain for all of [the] channels on which the node is a consenter.
joealewine
force-pushed
the
partorderer
branch
2 times, most recently
from
10ffe46
to
a20d90a
Compare
joealewine
force-pushed
the
partorderer
branch
from
a20d90a
to
88b0289
Compare
| @@ -191,7 +194,7 @@ Among the parameters in ``orderer.yaml``, there are: | |||
|
|
|||
| For more information about ``orderer.yaml`` and its specific parameters, check out :doc:`deployorderer/ordererchecklist`. | |||
|
|
|||
| When you're comfortable with how your ordering node has been configured, how your volumes are mounted, and your backend configuration, you can run the command to launch the ordering node (this command will depend on your backend configuration). | |||
| Note: This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to :doc:`create_channel/create_channel_participation`. For information on how to create an orderer that will bootstrapped with a system channel genesis block, check out `Deploy the ordering service <https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployment_guide_overview.html>`_ from the Fabric v2.2 documentation. | |||
There was a problem hiding this comment.
| Note: This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to :doc:`create_channel/create_channel_participation`. For information on how to create an orderer that will bootstrapped with a system channel genesis block, check out `Deploy the ordering service <https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployment_guide_overview.html>`_ from the Fabric v2.2 documentation. | |
| Note: This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to :doc:`create_channel/create_channel_participation`. For information on how to create an orderer that will be bootstrapped with a system channel genesis block, check out `Deploy the ordering service <https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployment_guide_overview.html>`_ from the Fabric v2.2 documentation. |
| @@ -204,7 +207,7 @@ When you're comfortable with how your ordering node has been configured, how you | |||
| Next steps | |||
| ---------- | |||
|
|
|||
| Blockchain networks are all about connection, so once you've deployed nodes, you'll obviously want to connect them to other nodes! If you have a peer organization and a peer, you'll want to join your organization to a consortium and join or :doc:`channels`. If you have an ordering node, you will want to add peer organizations to your consortium. You'll also want to learn how to develop chaincode, which you can learn about in the topics :doc:`developapps/scenario` and :doc:`chaincode4ade`. | |||
| Blockchain networks are all about connection, so once you've deployed nodes, you'll obviously want to connect them to other nodes! If you have a peer organization and a peer, you'll want to join your organization to a consortium and join or :doc:`create_channel/create_channel_participation`. If you have an ordering node, you will want to add peer organizations to your consortium. You'll also want to learn how to develop chaincode, which you can learn about in the topics :doc:`developapps/scenario` and :doc:`chaincode4ade`. | |||
There was a problem hiding this comment.
Just wondering... what does the text look like when rendered for the doc links? Specifically, what does "you'll want to join your organization to a consortium and join or ________" end up as?
There was a problem hiding this comment.
There was a problem hiding this comment.
Fabric PRs all include a Doc build link if you scroll to the status checks at the bottom.
| @@ -204,7 +207,7 @@ When you're comfortable with how your ordering node has been configured, how you | |||
| Next steps | |||
| ---------- | |||
|
|
|||
| Blockchain networks are all about connection, so once you've deployed nodes, you'll obviously want to connect them to other nodes! If you have a peer organization and a peer, you'll want to join your organization to a consortium and join or :doc:`channels`. If you have an ordering node, you will want to add peer organizations to your consortium. You'll also want to learn how to develop chaincode, which you can learn about in the topics :doc:`developapps/scenario` and :doc:`chaincode4ade`. | |||
| Blockchain networks are all about connection, so once you've deployed nodes, you'll obviously want to connect them to other nodes! If you have a peer organization and a peer, you'll want to join your organization to a consortium and join or :doc:`create_channel/create_channel_participation`. If you have an ordering node, you will want to add peer organizations to your consortium. You'll also want to learn how to develop chaincode, which you can learn about in the topics :doc:`developapps/scenario` and :doc:`chaincode4ade`. | |||
There was a problem hiding this comment.
Super nit, but every where else in the paragraph you use "you'll".
| Blockchain networks are all about connection, so once you've deployed nodes, you'll obviously want to connect them to other nodes! If you have a peer organization and a peer, you'll want to join your organization to a consortium and join or :doc:`create_channel/create_channel_participation`. If you have an ordering node, you will want to add peer organizations to your consortium. You'll also want to learn how to develop chaincode, which you can learn about in the topics :doc:`developapps/scenario` and :doc:`chaincode4ade`. | |
| Blockchain networks are all about connection, so once you've deployed nodes, you'll obviously want to connect them to other nodes! If you have a peer organization and a peer, you'll want to join your organization to a consortium and join or :doc:`create_channel/create_channel_participation`. If you have an ordering node, you'll want to add peer organizations to your consortium. You'll also want to learn how to develop chaincode, which you can learn about in the topics :doc:`developapps/scenario` and :doc:`chaincode4ade`. |
There was a problem hiding this comment.
Right. Just breaking it up so it's not quite so monotonous sounding.
| MaxRequestBodySize: 1 MB | ||
| ``` | ||
|
|
||
| * **`Enabled`**: If you are bootstrapping the ordering node with a system channel genesis block, this should remain `false`. If you are **not** bootstrapping the ordering node with a system channel genesis block, this should be overridden to `true`. Make sure that your [`General.BoostrapMethod`](#general-boostrapmethod) is set to `none` if `ChannelParticipation.Enabled` is set to `true`, otherwise you will get an error when you attempt to start the node. |
There was a problem hiding this comment.
Actually, there's no reason they can't/shouldn't enable the channel participation API when using a system channel that I can think of. They'll receive errors for any forbidden actions (join/remove application channels) but they'll have access to listing all the channels as well as individual channel details.
There was a problem hiding this comment.
Speaking of... where did this come from? I don't think anything's changed that would result in an error at startup with the channel participation API enabled and the file bootstrap method. Did you notice a log message suggesting this? If so, can you point out the message you noticed?
There was a problem hiding this comment.
I can't recall where this came from, exactly. I thought I heard it somewhere, but I suppose it's possible I just assumed it.
I assume this general guidance here is correct, and that this is at least recommended. I'll edit this to remove everything starting with "otherwise". Let me know if I should go farther.
There was a problem hiding this comment.
There was a problem hiding this comment.
I suppose I'd encourage users to enable the channel participation API, if for no other reason than giving them the ability to list channels and migrate away. I wouldn't say it's critical, and it's fine not to enable it. I suppose we're looking to give concrete advice on "this should be enabled, or this should not be enabled" though, so I would err towards turn it on.
There was a problem hiding this comment.
I'd suggest remove all the extra language and just say to enable it if you'd like to use the channel management APIs.
There was a problem hiding this comment.
The reason we disabled it in the defaults, is because Admin TLS is also disabled by default. We didn't want an unsecured service. So I guess we should at least say if you enable it, make sure you've enabled Admin TLS.
| This tutorial is based on the Raft consensus protocol and can be used to build an ordering service, which is comprised of ordering nodes, or "orderers". It describes the process to create a three-node Raft ordering service where all of the ordering nodes belong to the same organization. | ||
| This tutorial is based on the Raft consensus protocol and can be used to build an ordering service, which is comprised of ordering nodes, or "orderers". It describes the process to create a three-node Raft ordering service where all of the ordering nodes belong to the same organization. This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to [Create a channel without a system channel](../create_channel/create-channel_participation.html). | ||
|
|
||
| For information on how to create an orderer that will bootstrapped with a system channel genesis block, check out [Deploy the ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployorderer/ordererdeploy.html) from the Fabric v2.2 documentation. |
There was a problem hiding this comment.
| For information on how to create an orderer that will bootstrapped with a system channel genesis block, check out [Deploy the ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployorderer/ordererdeploy.html) from the Fabric v2.2 documentation. | |
| For information on how to create an orderer that will be bootstrapped with a system channel genesis block, check out [Deploy the ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployorderer/ordererdeploy.html) from the Fabric v2.2 documentation. |
| - `General.LocalMSPDir` - Path to the ordering node MSP folder. | ||
| - `General.LocalMSPID` - MSP ID of the ordering organization as specified in the channel configuration. | ||
| - `FileLedger.Location` - Location of the orderer ledger on the file system. | ||
| - `FileLedger.Location` - Location on the file system to the ledgers of the channels this orderer will be servicing. | ||
| - `ChannelParticipation.Enabled` - Set to `true`. This allows the orderer to be joined to an application without joining a system channel first. |
There was a problem hiding this comment.
| - `ChannelParticipation.Enabled` - Set to `true`. This allows the orderer to be joined to an application without joining a system channel first. | |
| - `ChannelParticipation.Enabled` - Set to `true`. This allows the orderer to be joined to an application channel without joining a system channel first. |
I assume this is what you meant.
| @@ -8,6 +8,8 @@ In a Hyperledger Fabric network, a node or collection of nodes together form wha | |||
|
|
|||
| Whereas Fabric networks that will only be used for testing and development purposes (such as our [test network](../test_network.html)) often feature an ordering service made up of only one node (these nodes are typically referred to as "orderers" or "ordering nodes"), production networks require a more robust deployment of at least three nodes. For this reason, our deployment guide will feature instructions on how to create a three-node ordering service. For more guidance on the number of nodes you should deploy, check out [Cluster considerations](#cluster-considerations). | |||
|
|
|||
| This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to [Create a channel without a system channel](../create_channel/create-channel_participation.html). For information on how to create an orderer that will bootstrapped with a system channel genesis block, check out [Deploy the ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployorderer/ordererdeploy.html) from the Fabric v2.2 documentation. | |||
There was a problem hiding this comment.
| This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to [Create a channel without a system channel](../create_channel/create-channel_participation.html). For information on how to create an orderer that will bootstrapped with a system channel genesis block, check out [Deploy the ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployorderer/ordererdeploy.html) from the Fabric v2.2 documentation. | |
| This tutorial assumes that a system channel genesis block will not be used when bootstrapping the orderer. Instead, these nodes (or a subset of them), will be joined to a channel using the process to [Create a channel without a system channel](../create_channel/create-channel_participation.html). For information on how to create an orderer that will be bootstrapped with a system channel genesis block, check out [Deploy the ordering service](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployorderer/ordererdeploy.html) from the Fabric v2.2 documentation. |
There was a problem hiding this comment.
It's crazy how many times I made this exact same typo.
joealewine
force-pushed
the
partorderer
branch
from
88b0289
to
8299ff2
Compare
Change-Id: If775789bd29f767aab3647a49ee019c5b7c2a6b6 Signed-off-by: joe-alewine <Joe.Alewine@ibm.com>
joealewine
force-pushed
the
partorderer
branch
from
8299ff2
to
fc692dc
Compare
|
@Mergifyio backport release-2.3 |
|
Command
|
Change-Id: If775789bd29f767aab3647a49ee019c5b7c2a6b6 Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> (cherry picked from commit 5446f10)
Change-Id: If775789bd29f767aab3647a49ee019c5b7c2a6b6 Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> (cherry picked from commit 5446f10)
Change-Id: If775789bd29f767aab3647a49ee019c5b7c2a6b6
Signed-off-by: joe-alewine Joe.Alewine@ibm.com
Type of change
Description
This doc edits the relevant sections in the orderer deployment guide to make the channel participation API process the default (and to link, where necessary, to the 2.2 version of the docs).