Orderer deploy guide edits for participation API (#2148)

Change-Id: If775789bd29f767aab3647a49ee019c5b7c2a6b6
Signed-off-by: joe-alewine <Joe.Alewine@ibm.com>

docs/source/create_channel/create_channel_participation.md

@@ -200,7 +200,7 @@ Because this tutorial demonstrates the process for creating a channel with **thr
 
 #### Configure the `orderer.yaml` file for each orderer
 
-Follow the instructions in the [ordering service deployment guide](../deployorderer/ordererdeploy.html) to build an ordering service with three ordering nodes. However, because the system channel is no longer required when you start an orderer, you can skip the entire process of [generating the genesis block](../deployorderer/ordererdeploy.html#creating-the-genesis-block) in those instructions. In addition, when you configure the `orderer.yaml` file for each orderer, there are a few other modifications you need to make to leverage this feature. You can refer to the orderer [sampleconfig](https://github.com/hyperledger/fabric/blob/{BRANCH}/sampleconfig/orderer.yaml) for more information about these parameters.
+Follow the instructions in the [ordering service deployment guide](../deployorderer/ordererdeploy.html) to build an ordering service with three ordering nodes. Note that when you configure the `orderer.yaml` file for each orderer, you will need to make modifications to the [`ChannelParticipation`](../deployorderer/ordererchecklist.html#channelparticipation) and [`General.BoostrapMethod`](../deployorderer/ordererchecklist.html#general-bootstrapmethod) parameters to leverage this feature.
 
 - `General.BootstrapMethod` - Set this value to `none`. Because the system channel is no longer required, the `orderer.yaml` file on each orderer needs to be configured with `BootstrapMethod: none` which means that no bootstrap block is required or used to start up the orderer.
 - `Admin.ListenAddress` - The orderer admin server address (host and port) that can be used by the `osnadmin` command to configure channels on the ordering service. This value should be a unique `host:port` combination to avoid conflicts.

docs/source/deployment_guide_overview.rst

@@ -37,6 +37,9 @@ In addition to the above, here is a sampling of the decisions you will need to m
 * **Database type.**
   Some channels in a network might require all data to be modeled in a way :doc:`couchdb_as_state_database` can understand, while other networks, prioritizing speed, might decide that all peers will use LevelDB. Note that channels should not have peers that use both CouchDB and LevelDB on them, as CouchDB imposes some data restrictions on keys and values. Keys and values that are valid in LevelDB may not be valid in CouchDB.
 
+* **Create a system channel or not.**
+  Ordering nodes can be bootstrapped with a configuration block for an administrative channel known as the “system channel” (from which application channels can be created), or simply started and joined to application channels as needed. The recommended method is to bootstrap without a configuration block, which is the approach this deployment guide assumes you will take. For more information about creating a system channel genesis block and bootstrapping an ordering node with it, check out `Deploying a production network <https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployment_guide_overview.html#creating-an-ordering-node>`_ from the Fabric v2.2 documentation.
+
 * **Channels and private data.**
   Some networks might decide that :doc:`channels` are the best way to ensure privacy and isolation for certain transactions. Others might decide that fewer channels, supplemented where necessary with :doc:`private-data/private-data` collections, better serves their privacy needs.
 
@@ -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`.
 
 The configuration values in an ordering node’s ``orderer.yaml`` file must be customized or overridden with environment variables. You can find the default ``orderer.yaml`` configuration file `in the sampleconfig directory of Hyperledger Fabric <https://github.com/hyperledger/fabric/blob/master/sampleconfig/orderer.yaml>`_.
 
@@ -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 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.
 
 .. toctree::
    :maxdepth: 1
@@ -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`.
 
 Part of the process of connecting nodes and creating channels will involve modifying policies to fit the use cases of business networks. For more information about policies, check out :doc:`policies/policies`.
 

docs/source/deployorderer/ordererchecklist.md

@@ -18,6 +18,8 @@ This checklist covers key configuration parameters for setting up a production o
 * [FileLedger.Location](#fileledger-location)
 * [Operations.*](#operations)
 * [Metrics.*](#metrics)
+* [Admin.*](#admin)
+* [ChannelParticipation.*](#channelparticipation)
 * [Consensus.*](#consensus)
 
 ## General.ListenAddress
@@ -140,7 +142,7 @@ In general, these four parameters would only need to be configured if you want t
 BootstrapMethod: file
 ```
 
-* **`BootstrapMethod`**: (default value should not be overridden) Unless you plan to use a file type other than “file”, this value should be left as is.
+* **`BootstrapMethod`**: If you plan to create this node on a network that is not using a system channel, override this value to `none` and then ensure that [`ChannelParticipation.Enabled`](#channelparticipation) is set to `true`, otherwise you will get an error when you attempt to start the node. If you are creating a node to be joined to a system channel, unless you plan to use a file type other than “file”, this value should be left as is.
 
 ## General.BoostrapFile
 
@@ -155,7 +157,7 @@ BootstrapMethod: file
 BootstrapFile:
 ```
 
-* **`BoostrapFile`**: (default value should be overridden) Specify the location and name of the system channel genesis block to use when this node is created.
+* **`BoostrapFile`**: (if you are creating this node to be joined to a system channel, the default value should be overridden) Specify the location and name of the system channel genesis block to use when this node is created. If you are creating this node without using a system channel, this value will not be used, and can therefore be left blank.
 
 ## General.LocalMSPDir
 
@@ -180,7 +182,7 @@ LocalMSPDir: msp
 LocalMSPID: SampleOrg
 ```
 
-* **`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).
+* **`LocalMSPID`**: (default value should be overridden) This identifies the organization this ordering node belongs to. The MSP ID must match the orderer organization MSP ID that exists in the configuration of any channel this joined will be joined to.
 
 ## General.BCCSP.*
 
@@ -308,6 +310,57 @@ Because Prometheus utilizes a "pull" model there is not any configuration requir
 * **`Provider`**: Set this value to `statsd` if using `StatsD` or `prometheus` if using `Prometheus`.
 * **`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.
 
+## Admin.*
+
+```
+Admin:
+    # host and port for the admin server
+    ListenAddress: 127.0.0.1:9443
+
+    # TLS configuration for the admin endpoint
+    TLS:
+        # TLS enabled
+        Enabled: false
+
+        # Certificate is the location of the PEM encoded TLS certificate
+        Certificate:
+
+        # PrivateKey points to the location of the PEM-encoded key
+        PrivateKey:
+
+        # Most admin service endpoints require client authentication when TLS
+        # is enabled. ClientAuthRequired requires client certificate authentication
+        # at the TLS layer to access all resources.
+        #
+        # NOTE: When TLS is enabled, the admin endpoint requires mutual TLS. The
+        # orderer will panic on startup if this value is set to false.
+        ClientAuthRequired: true
+
+        # Paths to PEM encoded ca certificates to trust for client authentication
+        ClientRootCAs: []
+```
+
+* **`ListenAddress`**: The orderer admin server address (host and port) that can be used by the `osnadmin` command to configure channels on the ordering service. This value should be a unique `host:port` combination to avoid conflicts.
+* **`TLS.Enabled`**: Technically this can be set to `false`, but this is not recommended. In general, you should always set this value to `true`.
+* **`TLS.Certificate`**: The path to and file name of the orderer signed certificate issued by the TLS CA.
+* **`TLS.PrivateKey`**: The path to and file name of the orderer private key issued by the TLS CA.
+* **`TLS.ClientAuthRequired`**: This value must be set to `true`. Note that while mutual TLS is required for all operations on the orderer `Admin` endpoint, the entire network is not required to use mutual TLS.
+* **`TLS.ClientRootCAs`**: The path to and file name of the admin client TLS CA root certificate.
+
+## ChannelParticipation.*
+
+```
+ChannelParticipation:
+    # Channel participation API is enabled.
+    Enabled: false
+
+    # The maximum size of the request body when joining a channel.
+    MaxRequestBodySize: 1 MB
+```
+
+* **`Enabled`**: If you are bootstrapping the ordering node with a system channel genesis block, this value can be set to either `true` or `false` (setting the value to `true` allows you to list channels and to migrate away from the system channel in the future). If you are **not** bootstrapping the ordering node with a system channel genesis block, this value must be set to `true` and the [`General.BoostrapMethod`](#general-boostrapmethod) should be set to `none`.
+* **`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.
+
 ## Consensus.*
 
 The values of this section vary by consensus plugin. The values below are for the `etcdraft` consensus plugin. If you are using a different consensus plugin, refer to its documentation for allowed keys and recommended values.