Deploy production ordering service doc

[joealewine]

Change-Id: Ib7631cf4974da7005ae4a6fa7c0939a5ebe6588c
Signed-off-by: joe-alewine Joe.Alewine@ibm.com

Type of change

• Documentation update

Description

Like the peer and CA deployment guides, this series of docs talks people through the process to plan and deploy an ordering service.

[joealewine]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[pamandrejko]

A few comments on the parameters.

[pamandrejko]

Unless #2078 gets ported back to release-2.2 we need to doc that ServerCertificate and ServerPrivateKey must be set (to the same values as the General.TLS.PrivateKey and General.TLS.Certificate.

[wlahti]

We'll make sure we backport it, just need to prioritize wrapping things up for release-2.3 at the moment.

[pamandrejko]

I think this should be (Default value should be overridden.) That's what we say in the peer deployment guide and since we are recommending that they setup their own folder structure to manage their MSPs and certs.

[pamandrejko]

Maybe you meant to leave this question in here for feedback?. I would change this section to match the peer recommendations:

    BCCSP.Default: If you plan to use a Hardware Security Module (HSM), then this must be set to PKCS11.
    BCCSP.PKCS11.*: Provide this set of parameters according to your HSM configuration. Refer to this [example]((../hsm.html) of an HSM configuration for more information.

[joealewine]

I did put that at the end and intended to delete this line.

[pamandrejko]

PKCS11 resides inside the BCCSP section no alongside it. I think we can make these recommendations match the peer recommendations for these parameters instead?

[pamandrejko]

The user running the orderer needs to own and have write access to this directory.

[joealewine]

Thanks for these comments, Pam!

[joealewine]

I did put that at the end and intended to delete this line.

[wlahti]

Suggested change

	Bote: the `ServerCertificate` and `ServerPrivateKey` must be set to the same values as the `General.TLS.PrivateKey` and `General.TLS.Certificate`.
	Note: the `ServerCertificate` and `ServerPrivateKey` must be set to the same values as the `General.TLS.PrivateKey` and `General.TLS.Certificate`.

[wlahti]

We'll make sure we backport it, just need to prioritize wrapping things up for release-2.3 at the moment.

[wlahti]

Suggested change

	**`LocalMSPID`**: (default value should be overridden) The MSP ID must match the orderer organization MSP ID that exists in the configuration of the system channel. This means the MSP ID must have been listen in the `configtx.yaml` used to create the genesis block of the system channel (or have been added later to the list of system channel administrators).
	**`LocalMSPID`**: (default value should be overridden) The MSP ID must match the orderer organization MSP ID that exists in the configuration of the system channel. This means the MSP ID must have been listed in the `configtx.yaml` used to create the genesis block of the system channel (or have been added later to the list of system channel administrators).

[wlahti]

Suggested change

	**`Location`**: (default value should be overridden, especially if more than node will be created by this organization) Every channel on which the node is a consenter will have its own subdirectory at this location. The user running the orderer needs to own and have write access to this directory.
	**`Location`**: (default value should be overridden, especially if more than one(?) node will be created by this organization) Every channel on which the node is a consenter will have its own subdirectory at this location. The user running the orderer needs to own and have write access to this directory.

[wlahti]

Suggested change

Note that the `configtx.yaml` that is shipped with Fabric binaries is identical to the [sample `configtx.yaml` found here](https://github.com/hyperledger/fabric/blob/master/sampleconfig/configtx.yaml), and contains the same channel "profiles" that are used to specify particular desired policies and parameters (for example, it can be used to which ordering nodes that are consenters in the system channel will be used in an application channel). When creating a channel (whether for an orderer system channel or an application channel), you specify a particular profile by name in your channel creation command, and that profile, along with the other parameters specified in `configtx.yaml`, are used to build the configuration block.

Note that the `configtx.yaml` that is shipped with Fabric binaries is identical to the [sample `configtx.yaml` found here](https://github.com/hyperledger/fabric/blob/master/sampleconfig/configtx.yaml), and contains the same channel "profiles" that are used to specify particular desired policies and parameters (for example, it can be used to specify(?) which ordering nodes that are consenters in the system channel will be used in an application channel). When creating a channel (whether for an orderer system channel or an application channel), you specify a particular profile by name in your channel creation command, and that profile, along with the other parameters specified in `configtx.yaml`, are used to build the configuration block.

[wlahti]

Suggested change

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 `etcd` protocol used by the ordering nodes.

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.

Or similar like raft or etcd/raft, plain etcd seems wrong to me on initial glance. I'm sure @jyellick will know the accurate way to reference it here.

[joealewine]

I'll change this one to etcdraft for now, as that seems like the right answer to me.

[wlahti]

Suggested change

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 processes that order and commit transactions for all channels on which the ordering node is a consenter (ordering nodes also validating actions in particular cases). The ordering node storage includes the blockchain for all of channels on which the node is a consenter.

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 processes that order and commit transactions 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.

[wlahti]

Suggested change

	The optimum number of ordering nodes for your ordering service ultimately depends on your use case, your resources, and your topology. However, clusters of three, five, seven, or nine nodes, are the most popular, with no more than about 50 channels per orderer.
	The optimal number of ordering nodes for your ordering service ultimately depends on your use case, your resources, and your topology. However, clusters of three, five, seven, or nine nodes, are the most popular, with no more than about 50 channels per orderer.

Nit: looks like this is an acceptable usage of the word but it seems uncommon.

[joealewine]

This one led me down a bit of a rabbit hole lol. They both seem fine but I don't mind changing this to optimal if it's the more common usage.

[wlahti]

Suggested change

The storage that should be allocated to an ordering node depends on factors such as the estimate transaction throughput, the size of blocks, and number of channels the node will be joined to. Your needs will depend on your use case. However, the best practice is to monitor the storage available to your nodes closely. You may also decide to enable an autoscaler, which will allocate more resources to your node, if your infrastructure allows it.

The storage that should be allocated to an ordering node depends on factors such as the estimated transaction throughput, the size of blocks, and number of channels the node will be joined to. Your needs will depend on your use case. However, the best practice is to monitor the storage available to your nodes closely. You may also decide to enable an autoscaler, which will allocate more resources to your node, if your infrastructure allows it.

[joealewine]

I think "expected" is actually better here, but thank you for flagging that "estimate" was definitely a typo.

[denyeart]

Suggested change

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 the ``orderer.yaml`` file but instead in the ``configtx.yaml`` file that is used to create the genesis block for the channel (this genesis block is used to bootstrap ordering nodes). 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. 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 the ``orderer.yaml`` file 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 application channel create transactions. For a look at the various decisions you will need to make, check out :doc:`deployorderer/ordererplan`.

[joealewine]

I didn't use "Application channel create transactions" but instead "and also used to generate the genesis block of application channels".

[denyeart]

Remove - orderers do not use gossip and there is nothing related to gossip in orderer.yaml.

[denyeart]

Orderers don't "send" blocks to peers. I've fixed that part here.
Also, the sentence "This separates..." goes in many unrelated directions, I didn't fix that part yet.

Suggested change

In a Hyperledger Fabric network, a node or collection of nodes together form what's called an "ordering service", which literally orders transactions into blocks and sends them to peers to be committed to their ledgers. This separates Fabric from other distributed blockchains, such as Ethereum and Bitcoin, in which this ordering is done by any and all nodes, requiring the establishment of probabilistic consensus algorithms which eventually guarantee ledger consistency to a high degree of probability, but which are still vulnerable to divergent ledgers (also known as a ledger “fork”), where different participants in the network have a different view of the accepted order of transactions.

In a Hyperledger Fabric network, a node or collection of nodes together form what's called an "ordering service", which literally orders transactions into blocks, which are then processed by peers and committed to their ledgers. This separates Fabric from other distributed blockchains, such as Ethereum and Bitcoin, in which this ordering is done by any and all nodes, requiring the establishment of probabilistic consensus algorithms which eventually guarantee ledger consistency to a high degree of probability, but which are still vulnerable to divergent ledgers (also known as a ledger “fork”), where different participants in the network have a different view of the accepted order of transactions.

[denyeart]

I think this paragraph is confusing because it starts off talking about channels and genesis block, and the reader will assume you are talking about application channels at first. I'd suggest introduce system channel first, then say ordering nodes are bootstrapped from the system channel genesis block, then say ordering nodes can also be consenters for application channels.

[denyeart]

Suggested change

This “system channel” is a special channel run by the ordering service and contains, among other things, the list of peer organizations that are allowed to create application channels (this list is known as the “consortium”). Although this system channel cannot be joined by peers or peer organizations (and thus, no transactions other than configuration transactions can be made on it), it does contain many of the same configuration parameters that application channels contain. Because application channels inherit these configuration values by default unless they are changed during the channel creation process, take care when creating your genesis block to keep the use case of your network in mind.

This “system channel” is a special channel run by the ordering service and contains, among other things, the list of peer organizations that are allowed to create application channels (this list is known as the “consortium”). Although this system channel cannot be joined by peers or peer organizations (and thus, no transactions other than configuration transactions can be made on it), it does contain many of the same configuration parameters that application channels contain. Because application channels inherit these configuration values by default unless they are changed during the channel creation process, take care when creating your system channel genesis block to keep the use case of your network in mind.

[denyeart]

Hang on, the first sentence of this section said we were going to create the genesis block of the system channel. We've jumped straight to an application channel creation here.

We need to do the steps in this order:

1. generate the system channel genesis block
2. use the system channel genesis block to bootstrap ordering nodes
3. generate application channel create transaction
4. create the application channel on the ordering service

The 'create a channel' tutorial already does these steps (at least steps 1,3,4). Do we want to document the steps twice, or just point to the create a channel tutorial?

[pamandrejko]

Good catch.
I grabbed the wrong profile.
I've updated the instructions to be more specific to the system channel genesis block.
and used the TwoOrgsOrdererGenesis: profile from the Test network instead.

For steps 3 and 4 I link to those instructions in the create a channel tutorial.

[denyeart]

Unlike the peer, the orderer.yaml separates the address and the port.

Suggested change

	**`ListenAddress`**: (default value should be overridden) This is the location where the orderer will listen, for example, `0.0.0.0:9051`.
	**`ListenAddress`**: (default value should be overridden) This is the location where the orderer will listen, for example, `0.0.0.0`.

[denyeart]

This comment is being added in PR #2123 :
# If not set, the server General.TLS.Certificate is re-used.

[denyeart]

This comment is being added in PR #2123 :
# If not set, the server General.TLS.PrivateKey is re-used.

[denyeart]

No, it doesn't have to be the same as General.TLS.Certificate.
It can be a different Certificate and PrivateKey pair. However, to keep the config simple, it is suggested to keep them the same.
As of v2.3.0, if unset, the ClientCertificate and ClientPrivateKey default to the server General.TLS.Certificate and General.TLS.PrivateKey.

[denyeart]

Suggested change

	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 it sends to the peers to be written to their ledgers.
	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 will then validate and commit to their ledgers.

[denyeart]

Suggested change

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 the ``orderer.yaml`` file 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. 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 orderer 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`.

[denyeart]

Beyond the suggestion I'm making in the first sentence, the last sentence is still too long and complex to understand. I'm not understanding the point you are trying to make... whether peer nodes participate in ordering or not has nothing to do with probabilistic consensus and potential forks. I think the entire last sentence could be removed.

Suggested change

In a Hyperledger Fabric network, a node or collection of nodes together form what's called an "ordering service", which literally orders transactions into blocks that are processed peers and committed to their ledgers. This separates Fabric from other distributed blockchains, such as Ethereum and Bitcoin, in which this ordering is done by any and all nodes, requiring the establishment of probabilistic consensus algorithms which eventually guarantee ledger consistency to a high degree of probability, but which are still vulnerable to divergent ledgers (also known as a ledger “fork”), where different participants in the network have a different view of the accepted order of transactions.

In a Hyperledger Fabric network, a node or collection of nodes together form what's called an "ordering service", which literally orders transactions into blocks, which peers will then validate and commit to their ledgers. This separates Fabric from other distributed blockchains, such as Ethereum and Bitcoin, in which this ordering is done by any and all nodes, requiring the establishment of probabilistic consensus algorithms which eventually guarantee ledger consistency to a high degree of probability, but which are still vulnerable to divergent ledgers (also known as a ledger “fork”), where different participants in the network have a different view of the accepted order of transactions.

[joealewine]

I think it's important for new users to understand that one of the key differences between Fabric and other blockchain networks is that the ordering process is performed by a dedicated node. This language is largely copied from the ordering service key concept doc. I think it's probably fine to stop at "any and all nodes", though.

[denyeart]

Doesn't have to be genesis block, can also be a later configuration block (note, this is why the orderer.yaml config option name changed from 'GenesisFile' to 'BootstrapFile' starting in v2.0.

Suggested change

	Every ordering node must be bootstrapped with a configuration block, known as the "genesis block", that contains configuration of a channel. While application channels also contain genesis blocks, the genesis block an ordering node is bootstrapped with is the genesis block of what’s called the “orderer system channel”.
	Every ordering node must be bootstrapped with a configuration block from the system channel, either the system channel "genesis block" or a later configuration block. This guide will assume you are creating a new ordering service and will therefore bootstrap ordering nodes from a system channel genesis block.

[denyeart]

This entry and others in this file are not on separate lines in the generated doc.

[denyeart]

Suggested change

	INFO 003 Generating new channel configtx
	INFO 004 Writing new channel tx
	INFO 004 Generating genesis block
	INFO 005 Creating system channel genesis block
	INFO 006 Writing genesis block

[denyeart]

Suggested change

	Make note of the generated `.pb` file. This is your genesis block and will be referenced in the `orderer.yaml` file below.
	Make note of the generated output block filename. This is your genesis block and will be referenced in the `orderer.yaml` file below.

[denyeart]

Suggested change

	- `General.BootstrapFile` - Path to and name of the genesis block `.pb` file for the ordering service system channel.
	- `General.BootstrapFile` - Path to and name of the genesis block file for the ordering service system channel.

[denyeart]

These two are optional as of v2.3 since they now default based on General.TLS.Certificate and General.TLS.PrivateKey

[pamandrejko]

Since this will be ported back to v2.2 I think we wanted to make another pass with updates like this for v2.3 after this gets merged for 2.2

[pamandrejko]

Although I did ask for this fix to be ported back to v2.2. Let me check if it made it in.

[pamandrejko]

It was backported here so we can add it

[joealewine]

Which too? Was this added and I missed it? @pamandrejko

[pamandrejko]

We have covered this in the checklist where we say:
As of Fabric v2.3.0, if unset, the ClientCertificate and ClientPrivateKey default to the server General.TLS.Certificate and General.TLS.PrivateKey when the orderer is not configured to use a separate cluster port.

Therefore I think we can remove the following two parameters from here since it would not be a typical use case to specify them.

• General.Cluster.ClientCertificate - Ordering node signed certificate (public key) from the TLS CA.
• General.Cluster.ClientPrivateKey - Ordering node private key from TLS CA.

[denyeart]

Actually, at this point, we are not ready to receive transactions from application clients, since we've only created the system channel, we haven't crated application channels yet.

[joealewine]

Thanks for these comments, Dave!

[joealewine]

I think it's important for new users to understand that one of the key differences between Fabric and other blockchain networks is that the ordering process is performed by a dedicated node. This language is largely copied from the ordering service key concept doc. I think it's probably fine to stop at "any and all nodes", though.

[denyeart]

This review focuses on the checklist.

[denyeart]

Suggested change

As you prepare to build a production ordering service (or a single ordering node, you need to customize the configuration by editing the [orderer.yaml](https://github.com/hyperledger/fabric/blob/{BRANCH}/sampleconfig/orderer.yaml) file, which is copied into the `/config` directory when downloading the Fabric binaries, and available within the Fabric ordering node image at `/etc/hyperledger/fabric/orderer.yaml`.

As you prepare to build a production ordering service (or a single ordering node), you need to customize the configuration by editing the [orderer.yaml](https://github.com/hyperledger/fabric/blob/{BRANCH}/sampleconfig/orderer.yaml) file, which is copied into the `/config` directory when downloading the Fabric binaries, and available within the Fabric ordering node image at `/etc/hyperledger/fabric/orderer.yaml`.

[denyeart]

Suggested change

	* **`RootCAs`**: (should be commented out) This parameter needs to be unset for normal use. It can be used to augment the orderer TLS certificate in the channel configuration orderer `MSPDir/tlscacerts` folder.
	* **`RootCAs`**: (should be commented out) This parameter needs to be unset for normal use. It can be used to augment the set of tlscacerts available from the MSPs of each channel's configuration.

[joealewine]

As I recall, the language that was here was suggested by Jason in the google doc this doc was created from. Also I'm not really sure how this one field in orderer.yaml can augment a set of TLS certs from multiple MSPs?

[denyeart]

Let's take test network as an example. There are three orgs in the channel config (orderer org, org1, org2). Each of these orgs has a tls ca cert in their msp/tlscacerts directory that gets encoded into the channel config. This set of three tls ca certs are used to verify connections. Now, at a later time, suppose one of those certs gets expired and the associated org is not able to immediately update their tls ca cert in the channel config. That org could provide a new tls ca cert, and it could be included in orderer.yaml for this orderer to augment the list of three from the channel config. So now it has a list of four (3 from channel config, one from orderer.yaml). This is consistent with what Jason said in the google doc - his main point was that any cert here would augment instead of override the list from the channel config.

This is a rare scenario, which is why we say it should be commented out, even in the sample orderer.yaml.

(Furthermore, I don't think this list is even used anymore, but that's a different story).

[jyellick]

+1 I think I may have used a '/' notation meaning "or", I did not mean an explicit path. Dave's wording is correct.

[joealewine]

Ok, great. Thank you both for clarifying this.

[denyeart]

Suggested change

	* **`ClientRootCAs`**: (Mutual TLS only) Can be left blank if mutual TLS is disabled. If mutual TLS is enabled, this is the path to the root certificate of the TLS CA.
	* **`ClientRootCAs`**: (Mutual TLS only) Can be left blank if mutual TLS is disabled. If mutual TLS is enabled, this is a list of the paths to the root certificate of the TLS CA for each client organization that will need to connect to the orderer.

[denyeart]

Jason made the same point about this one in the google doc actually, which I missed during my initial review... the set of org tls ca certs from the channel config will be used to verify client connections. You can add additional tls ca certs in ClientRootCAs to augment that list. Again, it would be rare.

[denyeart]

"Provide the path to and file name" doesn't sound correct. This is repeated multiple times below.

[joealewine]

I think it's just missing commas: "Provide the path to, and filename of,"

[denyeart]

Suggested change

	In general, these four parameters would only need to be configured if you want to configure multiple listeners for your orderers. In most circumstances a single listener is sufficient. Either set these four parameters together or leave them unset.
	In general, these four parameters would only need to be configured if you want to configure a separate listener and TLS certificates for intra-cluster communication (with other Raft orderers), as opposed to using the listener that peer clients and application clients utilize. This is an advanced deployment option. Either set these four parameters together or leave them unset.

[denyeart]

The PKCS11 section should be listed in the sample config above.

[denyeart]

Suggested change

	* **`Certificate`**: (required when using the operations service) Can be the same file as the `orderer.tls.cert.file`.
	* **`Certificate`**: (required when using the operations service) Can be the same file as the `General.TLS.Certificate`.

[denyeart]

Suggested change

	* **`PrivateKey`**: (required when using the operations service) Can be the same file as the `orderer.tls.key.file`.
	* **`PrivateKey`**: (required when using the operations service) Can be the same file as the `General.TLS.PrivateKey`.

[denyeart]

I know that lowercase values work. Not sure about the mixed case values unless somebody has mentioned this.

[joealewine]

I used "StatsD" to refer to StatsD generally (as this is the proper capitalization from what I could find online, but used the capitalization from the YAML when explicitly referring to the YAML.

[denyeart]

It doesn't matter what case is used online or in the YAML keys. The valid values for Metrics.Provider are:
"disabled"
"statsd"
"prometheus"

[denyeart]

Suggested change

	* **`Statsd.Address`**: (required to use `StatsD` or `Prometheus` metrics for the ordering node) When `StatsD` is enabled, you will need to configure the `hostname` and `port` of the `StatsD` server so that the ordering node can push metric updates.
	* **`Statsd.Address`**: (required to use `StatsD` metrics for the ordering node) When `StatsD` is enabled, you will need to configure the `hostname` and `port` of the `StatsD` server so that the ordering node can push metric updates.

[denyeart]

Was this a copy/paste from somewhere? The description is confusing... I was expecting it to describe what a TLS CA root certificate is, not what a certificate is in general.

[joealewine]

It's basically identical to what we have in the peer deployment guide.

[denyeart]

Ok, that's why I asked if it was copy/paste, so that we can fix in both places. Lets just leave it as "TLS CA Root certificate", I feel talking about public and private signing keys are only going to confuse people, as it gives the impression these certs are going to be used for signing transactions or communications. They're not, they're only used for verifying issued certs.

[joealewine]

Ok done.

[denyeart]

Was this a copy/paste from somewhere? The description is confusing... I was expecting it to describe what a CA root certificate is, not what a certificate is in general.

[joealewine]

It's basically identical to what we have in the peer deployment guide.

[denyeart]

Ok, that's why I asked if it was copy/paste, so that we can fix in both places. Lets just leave it as "CA Root certificate", I feel talking about public and private signing keys are only going to confuse people, as it gives the impression these certs are going to be used for signing transactions or communications. They're not, they're only used for verifying issued certs.

[joealewine]

Ok done.

[denyeart]

The TLS CA root cert from EACH org that is going to connect to the orderer should be copied, that is, application clients and peers that will connect to this orderer.

[joealewine]

In this tutorial, there's only one org. But I'll add a clarification note here anyway.

[denyeart]

Suggested change

The first channel that is created in a Fabric network is the "system" channel. The system channel defines the set of ordering nodes that form the ordering service and the set of organizations that serve as ordering service administrators. Peers transact on private "application" channels that are derived from the ordering service system channel, which also defines the "consortium" (the peer organizations known to the ordering service). Therefore, before you can deploy an ordering service, you need to generate the system channel configuration by creating the "genesis block". abric provides the `configtxgen` tool for this purpose. We'll then use the generated system channel genesis block to bootstrap each ordering node.

The first channel that is created in a Fabric network is the "system" channel. The system channel defines the set of ordering nodes that form the ordering service and the set of organizations that serve as ordering service administrators. Peers transact on private "application" channels that are derived from the ordering service system channel, which also defines the "consortium" (the peer organizations known to the ordering service). Therefore, before you can deploy an ordering service, you need to generate the system channel configuration by creating the system channel "genesis block". Fabric provides the `configtxgen` tool for this purpose. We'll then use the generated system channel genesis block to bootstrap each ordering node.

[denyeart]

This paragraph seems to talk about application channels, while the prior paragraph and next paragraphs talk about system channel genesis block creation. I'd highlight that configtxgen is used for both.

[joealewine]

I don't get an "application channel" vibe from this. Not sure exactly what you're referring to. I changed this first sentence to:

"Both the system channel and all application channels are created by building a channel creation transaction and submitting the transaction to the ordering service."

Does that help?

[denyeart]

No.
"All channels are created by building a channel creation transaction and submitting the transaction to the ordering service."
That is true for application channels.
It is not true for system channels. First of all, if you are creating the system channel there is not yet an ordering service to submit to! Second of all, for the system channel you generate a system channel genesis block (not a channel create transaction).

[joealewine]

The simplest solution here seemed to be to just cut everything before the sentence beginning with "While it is possible", as that's really what's relevant to setting up configtxgen.

[jyellick]

+1 I think I may have used a '/' notation meaning "or", I did not mean an explicit path. Dave's wording is correct.

[jyellick]

... when the orderer is not configured to use a separate cluster port.

[jyellick]

Perhaps we should be saying "all six parameters" here and above? It's a little awkward because you may only set the first two, but if you set the last four, the first two must be set as well.

[joealewine]

Yes that is a bit awkward. I went with: "These four parameters should be set together or left unset, and if they are set, note that the ClientCertificate and ClientPrivateKey must be set as well."

Perhaps not the best sentence in the history of the English language, but hopefully it makes the point.

[jyellick]

I'm a little confused why having more than one node means this location should be overridden? I guess you could put the host name into the path in the container, but you could also just name your volume properly.

My guess is, you are referring to running two non-containerized binaries on the same host. But it's odd here that we assume this, while below for the operations endpoint we talk about "in the unlikely event where two ordering nodes are running on the same node"

[joealewine]

Ok changed this to "(default value should be overridden in the unlikely event where two ordering nodes are running on the same node)"

[jyellick]

These seems like it was copied maybe? But it's very misleading to me.

if you want to monitor the metrics for the orderer, you need to use StatsD as your metric provider

You can monitor metrics using prometheus too? I would think it should read: "if you want to monitor the metrics for the orderer, you must set this value to either statsd or prometheus. Then have a paragraph about each.

[joealewine]

Seems sufficient to me to just link to the metrics reference doc, but if we want to add a paragraph of information here for each metrics type, I'm open to it. Not being an expert on metrics, I'm not really sure what we should say, though.

[jyellick]

I think this is my text verbatim, but I think perhaps it might make more sense to say something like:

"The values of this section vary by consensus plugin. If you are using the recommended etcdraft consensus plugin, see the following documentation. If you are using a different consensus plugin, refer to its documentation for allowed keys and recommended values.

[jyellick]

it's a little odd that for WALDir and SnapDir, we don't mention that these needs to be on volumes, but we do for the ledger. It's critical that these not be destroyed (and we have seen a lot of users make the mistake of not preserving them).

[denyeart]

Suggested change

	* **`ClientRootCAs`**: (Mutual TLS only) Can be left blank if mutual TLS is disabled. If mutual TLS is enabled, this is a list of the paths to the root certificate of the TLS CA for each client organization that will need to connect to the orderer.
	* **`ClientRootCAs`**: (Mutual TLS only) Can be left blank if mutual TLS is disabled. If mutual TLS is enabled, this is a list of the paths to additional root certificates used for verifying certificates of client connections. It can be used to augment the set of tlscacerts available from the MSPs of each channel’s configuration.

[denyeart]

Suggested change

	* **`RootCAs`**: (should be commented out) This parameter needs to be unset for normal use. It can be used to augment the set of tlscacerts available from the MSPs of each channel's configuration.
	* **`RootCAs`**: (should be commented out) This parameter is typically unset for normal use. It is a list of the paths to additional root certificates used for verifying certificates of other orderer nodes during outbound connections. It can be used to augment the set of tlscacerts available from the MSPs of each channel's configuration.

[denyeart]

Link not working.

[denyeart]

I believe this entire bullet (line 80) relates to General.TLS.ClientRootCAs, which is not common to be set, as explained in the property checklist. Therefore I'd recommend to remove this entire bullet, as it is more likely to confuse than help. In the rare cases where people need to set it, they can see the reference explanation in the checklist.

[pamandrejko]

This was ported back to v2.2 as well. Do we need to even call out the release then?

[pamandrejko]

We have covered this in the checklist where we say:
As of Fabric v2.3.0, if unset, the ClientCertificate and ClientPrivateKey default to the server General.TLS.Certificate and General.TLS.PrivateKey when the orderer is not configured to use a separate cluster port.

Therefore I think we can remove the following two parameters from here since it would not be a typical use case to specify them.

• General.Cluster.ClientCertificate - Ordering node signed certificate (public key) from the TLS CA.
• General.Cluster.ClientPrivateKey - Ordering node private key from TLS CA.

comments addressed

[joealewine]

@Mergifyio backport release-2.2

[joealewine]

@Mergifyio backport release-2.1

[mergify]

Command backport release-2.2: success

Backports have been created

• #2138 Deploy production ordering service doc (bp #2080) has been created for branch release-2.2

[mergify]

Command backport release-2.1: success

Backports have been created

• #2139 Deploy production ordering service doc (bp #2080) has been created for branch release-2.1