[FAB-18179] Channel Participation API tutorial #2081

pamandrejko · 2020-11-06T15:25:25Z

Signed-off-by: pama-ibm pama@ibm.com

Introduce the Channel Participation API via a new tutorial that contains the steps for using the osnadmin CLI with your existing ordering service or by creating a new one.

Type of change

Documentation update

Description

Content coexists with the osnadmin CLI command documentation in PR #2077

Additional details

Related issues

FAb017712

Release Note

Fabric v2.3 introduces the ability to create channels between network members without requiring an ordering service system channel. This feature greatly simplifies the channel creation process and provides a mechanism for Raft consenters to join a channel with zero downtime. See the new tutorial to learn more and get started with this new feature.

wlahti

Only made it about halfway through for now. I'll get back to reviewing this later but wanted to get my current comments out there.

docs/source/create_channel/create_channel_participation.md

wlahti · 2020-11-09T22:48:27Z

docs/source/create_channel/create_channel_participation.md

+    orderer start
+    ```
+
+When the ordering service starts successfully and a Raft leader is elected, you should see something similar to the following output:


This needs to be updated as it refers to the system channel startup. Perhaps include some different logs including this one here that we look for in our integration tests.

changed it to:
INFO 01d Registrar initializing without a system channel, number of application channels: 1, with 1 consensus.Chain(s) and 0 follower.Chain(s)
INFO 01e This node is picked to start campaign channel=channel1 node=2
INFO 01f Starting orderer:

wlahti · 2020-11-09T22:52:03Z

docs/source/create_channel/create_channel_participation.md

+
+## Step one: Generate the genesis block of the channel
+
+Channels are created by building a channel creation transaction, also referred to as the "genesis block", and submitting the transaction to the ordering service. The channel creation transaction specifies the initial configuration of the channel and is used by the ordering service to write the channel genesis block. While only one member needs to create the genesis block, it can be shared out of band with the other members on the channel who can inspect it to ensure they agree to the channel configuration and then used by each orderer.


The first part of this reads like the old flow instead of the new. In the channel participation flow, you create (or receive from somebody else) the genesis block for the channel and submit it your orderer in the join request. The block submitted is the genesis block and is added to the ledger as-is.

docs/source/create_channel/create_channel_participation.md

wlahti · 2020-11-09T23:01:39Z

docs/source/create_channel/create_channel_participation.md

+```
+2020-03-11 16:37:12.695 EDT [common.tools.configtxgen] main -> INFO 001 Loading configuration
+2020-03-11 16:37:12.738 EDT [common.tools.configtxgen.localconfig] Load -> INFO 002 Loaded configuration: /Usrs/fabric-samples/test-network/configtx/configtx.yaml
+2020-03-11 16:37:12.740 EDT [common.tools.configtxgen] doOutputChannelCreateTx -> INFO 003 Generating new channel configtx
+2020-03-11 16:37:12.789 EDT [common.tools.configtxgen] doOutputChannelCreateTx -> INFO 004 Writing new channel tx
+```


This looks like it was generated by the -createChannelTx command and not -outputBlock. :)

Changed it to:
INFO 001 Loading configuration
INFO 002 orderer type: etcdraft
INFO 003 Loaded configuration: /fabric/config/configtx.yaml
INFO 004 Generating genesis block
INFO 005 Writing genesis block

docs/source/create_channel/create_channel_participation.md

wlahti · 2020-11-09T23:06:10Z

docs/source/create_channel/create_channel_participation.md

+
+When successful, the channel is created with a ledger height `1`. Because this orderer is joining from the genesis block, the `status` is "active". And because the orderer is part of the channel consenter, its `consensusRelation` is "consenter". We delve more into the `consensusRelation` value in the next section.
+
+You can repeat the same command on the other two orderers. Because these two orderers join the channel from the genesis block and are part of the consenter set, their status transitions almost immediately from  "onboarding" to "active" and the "consensusRelation" status is "consenter". At this point, the channel becomes operational because the default policy of a MAJORITY of consenters (as defined in the channel configuration) are "active".


This isn't policy related, right? It's just that raft requires a majority to form quorum.

docs/source/create_channel/create_channel_participation.md

wlahti · 2020-11-09T23:19:21Z

docs/source/create_channel/create_channel_participation.md

- * **Ordering service consortium no longer required** - You no longer need to define the set of organizations, also referred to as the "consortium", to transact on an application channel.
- * **Channel simplicity** - There is no longer the concept of a system channel or an application channel. There is simply a "channel" that allows two or more organizations to transact on the blockchain network. Each channel is administered separately, and each ordering service node can join or leave as needed.
+ * **System channel no longer required**: Previously a channel managed by the ordering service (called the "system channel") was defined using the `configtxgen` tool to create a genesis block. This channel was exclusively managed by the ordering service and was the template on which all application channels were based. Besides the creation of the system representing an extra step (as compared to the new process), this system channel created an extra layer of administration that, for some use cases, provided no tangible benefit.
+ * **Consortium no longer required**: You no longer need to define the set of organizations, known as the "consortium", who are permitted to create channels on a particular ordering service. With this new process, **all channels are application channels**, so the concept of a list of organizations who can create channels no longer applies. Any set of organizations can get together and create a channel using a defined set of ordering nodes (which become the ordering service of that channel). Additionally, if the MSP of the peer organization, as listed in the system channel, needs to be changed, the peer organization to coordinate with an orderer organization to change the MSP.


Additionally, if the MSP of the peer organization, as listed in the system channel, needs to be changed, the peer organization to coordinate with an orderer organization to change the MSP. This reads as halfway in between what I think you were going for. Do you want to highlight that you no longer need to coordinate with an orderer organization here?

I think some words were accidentally dropped in there. I changed it to:
Additionally, if the MSP of the peer organization, as listed in the system channel, needs to be changed, the peer organization no longer needs to to coordinate with an orderer organization to change the MSP.

docs/source/create_channel/create_channel_participation.md

pamandrejko · 2020-11-11T17:02:39Z

/azp run

azure-pipelines · 2020-11-11T17:02:54Z

Azure Pipelines successfully started running 1 pipeline(s).

wlahti · 2020-11-12T14:03:21Z

docs/source/create_channel/create_channel_participation.md

+**How this process differs from the legacy process:**
+
+ * **System channel no longer required**: Previously a channel managed by the ordering service (called the "system channel") was defined using the `configtxgen` tool to create a genesis block. This channel was exclusively managed by the ordering service and was the template on which all application channels were based. Besides the creation of the system representing an extra step (as compared to the new process), this system channel created an extra layer of administration that, for some use cases, provided no tangible benefit.
+ * **Consortium no longer required**: You no longer need to define the set of organizations, known as the "consortium", who are permitted to create channels on a particular ordering service. With this new process, **all channels are application channels**, so the concept of a list of organizations who can create channels no longer applies. Any set of organizations can get together and create a channel using a defined set of ordering nodes (which become the ordering service of that channel). Additionally, if the MSP of the peer organization, as listed in the system channel, needs to be changed, the peer organization no longer needs to coordinate with an orderer organization to change the MSP.


The all channels are application channels bit isn't technically accurate, but for the sake of this document it's probably what we want to include/recommend. You can still create a system channel genesis block and use the API to create the system channel (or onboard a new orderer to an existing system channel).

This is an important point - thank you for mentioning it because I had not really considered it. My thinking though is that since this is a tutorial about creating a channel without a system channel, it doesn't really fit in this topic per se and could be confusing. I think we should def include this as appropriate when we update all the other topics that talk about the system channel though.

docs/source/create_channel/create_channel_participation.md

wlahti · 2020-11-12T14:09:46Z

docs/source/create_channel/create_channel_participation.md

+  "url": "participation/v1/channels/channel1",
+  "status": "active",
+  "consensusRelation": "consenter",
+  "height": 1152


For accuracy, this would be 1153 now after the config update to add the orderer to the consenters set. :)

Had not even considered this. Yes. good catch. Done.

For completeness: If the config block used for join was at 1151, and there were, say, 1000 normal blocks after it, then the config block which added OSN4 would be at 2152,

@tock-ibm Not sure I have captured this correctly?
Note that if the config block specified on the join command was at a height of `1151`, and there were `1000` other blocks after it, then the config block that adds `OSN4` as a consenter would be at `2152`.

docs/source/create_channel/create_channel_participation.md

tock-ibm · 2020-11-12T17:30:59Z

docs/source/create_channel/create_channel_participation.md

+
+When successful, the channel is started with a ledger height `1`. Because this orderer is joining from the genesis block, the `status` is "active". And because the orderer is part of the channel's consenter set, its `consensusRelation` is "consenter". We delve more into the `consensusRelation` value in the next section.
+
+You can repeat the same command on the other two orderers. Remember to update the `OSN_TLS_SIGN_CERT` and `OSN_TLS_PRIVATE_KEY` environment variables to point to the certificates for the corresponding orderer. Because these two orderers join the channel from the genesis block and are part of the consenter set, their status transitions almost immediately from  "onboarding" to "active" and the "consensusRelation" status is "consenter". At this point, the channel becomes operational because a majority of consenters (as defined in the channel configuration) are "active". You should see something similar to the following in your orderer logs:


Again, these (the OSN_TLS_SIGN_CERT and OSN_TLS_PRIVATE_KEY) are actually the client's certificate and key. They can stay the same.

If all 3 orderers come from the same org and have the same ROOT CA, then the only thing that needs to change it the orderer endpoint: -o OSN1.example.com:7050 -> -o OSN2.example.com:7050

Thanks for this. I changed it to
Remember to update the orderer endpoint, `-o [ORDERER_ADMIN_LISTENADDRESS]`, on the command for the corresponding orderer.

docs/source/create_channel/create_channel_participation.md

tock-ibm · 2020-11-12T17:41:09Z

docs/source/create_channel/create_channel_participation.md

+  "height": 1152
+}


1151, actually; as the follower pulls the config-block that corresponds to the join-block given to it, it changes to "active".

However, it is important to note that the transition from "onboarding" to "active" is not the only criteria used to decide whether it is the right time to add the new OSN to the channel's consenters set. What it more important is the height that the new OSN reached, compared to the height of the consenters. For example, the last config block may be at height 1151, but there might be a huge number of normal block after it.... After OSN4 becomes "active" (caught up to the last config), it is better to compare the height of OSN1 with that of OSN4, and if they are "close enough" - only then add OSN4 to the consenters set of the channel.

This is a really good point. I added this:
However, it is important to note that the transition from **onboarding** to **active** should not be the only criteria used to decide whether it is the right time to add the new orderer to the channel's consenters set. What is more important is the height that the new orderer reached, compared to the height of the consenters. For example, the specified config block may be at height `1151`, but there could be a huge number of normal blocks that follow. After `OSN4` becomes **active** (caught up to the specified config), it is better to compare the height of `OSN1` with that of `OSN4`, and if they are close enough to each other -- only then add `OSN4` to the consenters set of the channel.

tock-ibm · 2020-11-12T17:55:19Z

docs/source/create_channel/create_channel_participation.md

+  "url": "participation/v1/channels/channel1",
+  "status": "active",
+  "consensusRelation": "consenter",
+  "height": 1152


For completeness: If the config block used for join was at 1151, and there were, say, 1000 normal blocks after it, then the config block which added OSN4 would be at 2152,

tock-ibm · 2020-11-12T17:57:35Z

docs/source/create_channel/create_channel_participation.md

+
+### Add or remove orderers from existing channels
+
+You can continue to use the `osnadmin channel join` and `osnadmin channel remove` commands to add and remove orderers on each channel according to your business needs.


I think it is important to mention that it is recommended to configure channel A and remove OSNx from the consenters set, prior to deleting channel A from orderer OSNx.

I added this statement:
Be aware that before you remove a channel from an orderer, you need to first remove the orderer from the channel's consenter set by submitting an channel update request.

You don't really need to do this, it is recommended. If the channel has fault tolerance, removing a channel from an orderer is equivalent to a single failure.

denyeart

Nice job folks!

Mostly nits...

denyeart · 2020-11-13T05:15:25Z

docs/source/create_channel/create_channel.md

@@ -1,4 +1,4 @@
-# Creating a new channel
+# Create a channel with a system channel (legacy)


In addition to updating the title, I think a sentence or note should be added to the beginning of this topic mentioning the new approach without system channel, and linking to the new tutorial.
I realize the overview topic lists both tutorials, but for people that land on this old page it would be good to notify them of the new approach and new tutorial.

Actually, I meant to add this to the docs/source/create_channel/create_channel_overview.rst topic too so users get a little guidance on which tutorial to pick and I forgot. So I'm grateful you brought this up. I've added a few lines to both topics now.

docs/source/create_channel/create_channel_participation.md

denyeart · 2020-11-13T05:28:31Z

docs/source/create_channel/create_channel_participation.md

+ * **Flexibility**: Whereas ordering nodes could only be part of a single ordering service, orderers can now join or leave channels as needed, similar to how peers can join any channel its organization is a member of.
+ * **Operational benefits**:
+    * Easy to list the channels that the ordering node is a consenter on.
+    * Simple process to delete a channel and the ledger associated with that channel.


"delete a channel"
I assume this is really talking about "removing a channel" from an ordering service node, rather than deleting a channel from the entire "network".

Also, I would not use the word "ledger" for ordering service nodes. I'd simply mention the channel's
associated "blocks".

Changed it to
* Simple process to remove a channel and the blocks associated with that channel.

docs/source/create_channel/create_channel_participation.md

denyeart · 2020-11-13T06:44:26Z

docs/source/create_channel/create_channel_participation.md

+
+```
+
+**Note:** For simplicity, this snippet assumes that the peers and orderers belong to the same organization `SampleOrg`. You can refer to the [sample config](https://github.com/hyperledger/fabric/blob/{BRANCH}/sampleconfig/configtx.yaml) for the full example. For a production deployment however, it is recommended that the peer and ordering nodes belong to separate organizations.


This tutorial switches back and forth between ordererOrg1.example.com and SampleOrg. This will likely confuse readers.

Good catch. I changed the note to
Note: For simplicity, this snippet assumes that the peers and orderers belong to the same organization SampleOrg. You can refer to the sample config for the full example. For a production deployment however, it is recommended that the peer and ordering nodes belong to separate organizations which is why this tutorial uses ordererOrg1.example.com for the orderer organization. If you are doing the same, throughout the configtx.yaml you would need to change all references of the orderer organization from SampleOrg to ordererOrg1.example.com. This would include adding a new orderer organization ordererOrg1.example.com to the Organizations: section of the file.

@denyeart If you are still concerned, we could refactor the tutorial to use SampleOrg instead if you think that would be better?

@pamandrejko I think it is fine with your clarification now. If we invest further, I'd recommend getting closer to test network configtx.yaml (with the separate orderer org) rather than getting closer to the sampleconfig configtx.yaml (with SampleOrg).

docs/source/create_channel/create_channel_participation.md

jyellick

Thanks for all the hard work on this, it's looking good. A few comments though.

jyellick · 2020-11-13T16:00:12Z

docs/source/create_channel/create_channel_participation.md

+
+ * **System channel no longer required**: Besides the creation of the system representing an extra step (as compared to the new process), this system channel created an extra layer of administration that, for some use cases, provided no tangible benefit.
+ * **Consortium no longer required**: You no longer need to define the set of organizations, known as the "consortium", who are permitted to create channels on a particular ordering service. With this new process, **all channels are application channels**, so the concept of a list of organizations who can create channels no longer applies. Any set of organizations can get together and create a channel using a defined set of ordering nodes (which become the ordering service of that channel).
+ * **Simplified ordering node creation process**: Because a genesis block no longer needs to exist before an ordering node is created, admins can now focus on the process of setting up their infrastructure and making sure their node is working correctly before joining a particular application channel. Additionally, because an ordering node no longer needs to scan the system channel ledger to determine which channels it is joined to and then replicate those ledgers, the node starts up more rapidly.


Additionally, because an ordering node no longer needs to scan the system channel ledger to determine which channels it is joined to and then replicate those ledgers, the node starts up more rapidly.

This isn't really true. The only time the orderer scans the system channel for channels is when bootstrapping from a late join config block. Otherwise, the existing ledgers are simply loaded. Where did this sentence/claim originate from?

The idea that orderers do not have to scan the ordering service for the channels anymore (and that this is an improvement over the old way) it is in the RFC under "scalability problems". It was my inference that this would help nodes start faster.

Should this whole sentence be deleted?

Given he said it not really true. I removed it.

docs/source/create_channel/create_channel_participation.md

jyellick · 2020-11-13T16:04:46Z

docs/source/create_channel/create_channel_participation.md

+ * **Operational benefits**:
+    * Easy to list the channels that the ordering node is a consenter on.
+    * Simple process to delete a channel and the ledger associated with that channel.
+    * Ordering nodes now detect that they have been added to a channel more quickly. Previously, this process could take several minutes, causing ordering node admins to restart their nodes so that the node could detect that it was joined more quickly.


Ordering nodes now detect that they have been added to a channel more quickly.

I guess this is in the section about benefits of the new process, but, my first reading implied that this was an overall improvement. Maybe it would be better to say something like: "Orderer nodes can now track channels as a follower before being added to a consenter, allowing them to detect this addition more quickly."

Done. * Orderer nodes can now track channels as a follower before being added to a channel's consenter set, allowing them to detect this addition more quickly. Previously, this process could take several minutes, causing ordering node admins to restart their nodes so that the node could detect that it was joined more quickly.

jyellick · 2020-11-13T16:05:28Z

docs/source/create_channel/create_channel_participation.md

+    * Ordering nodes now detect that they have been added to a channel more quickly. Previously, this process could take several minutes, causing ordering node admins to restart their nodes so that the node could detect that it was joined more quickly.
+    * If the MSP of a peer organization, as listed in the system channel, needs to be changed, the peer organization no longer needs to coordinate with an orderer organization to change the MSP.
+
+**Note: the new mode of creating channels is incompatible with creating a channel using a system channel. If the system channel exists, the `Join` and `Remove` operations will not be supported. Similarly, they cannot be used with a Solo or Kafka ordering service.**


Maybe it's too detailed here, but Remove works, but only for the system channel.

I changed it to:
Note: the new mode of creating channels is incompatible with creating a channel using a system channel. If the system channel exists, the channel join operation is not be supported. Similarly, channel join and channel remove cannot be used with a Solo or Kafka ordering service.

jyellick · 2020-11-13T16:17:01Z

docs/source/create_channel/create_channel_participation.md

+
+- [Prerequisites](#prerequisites)
+- [Step one: Generate the genesis block of the channel](#step-one-generate-the-genesis-block-of-the-channel)
+- [Step two: Use the osnadmin CLI to create the channel](#step-two-use-the-osnadmin-cli-to-create-the-channel)


I suppose this could devolve into a philosophical debate, but I would argue the channel is created when the genesis block is created. The channel isn't very useful though until the orderer joins and begins to participate in consensus for that channel.

I'm also a bit confused why joining the first node is somehow a special step, while joining additional nodes is a separate step. The channel will not be usable until enough nodes to form quorum have been joined.

We decided to include 2 steps here because
Step two is about consenters and step three is about followers.
It felt like a logical way to break up all the content.

I do see your point though. I changed it to
Step two: Use the osnadmin CLI to add the first orderer to the channel
although in that step we join all 3 orderers so I'm thinking of simplifying it to
Step two: Use the osnadmin CLI to join the orderers to the channel
But then
Step three: Join additional ordering nodes
is confusing. I agree. I need to think on this a little more. I was trying to avoid using the terms consenter/ follower since is has not been introduced yet in the topic.

docs/source/create_channel/create_channel_participation.md

jyellick · 2020-11-13T16:33:29Z

docs/source/create_channel/create_channel_participation.md

+
+## Step two: Use the `osnadmin` CLI to start the channel
+
+Now that the genesis block has been created, the first ordering node that receives the `osnadmin channel join` command command effectively "activates" the channel, though the channel is not fully operational until a quorum of consenters is established (if your profile listed three consenters, at least one more node, for a total of two, would have to join using the `osnadmin channel join` command).


I'm really not sure what "activates" is supposed to mean. If you subsequently remove the channel from the first orderer, is it still activated? From a peer perspective, how does is an "activated" channel different from one that is not?

I guess the question really is "If a channel genesis block is created, but nobody joins it, does the channel exist?" I would argue that it does.

I added this --- I was trying to avoid the philosophical question about when a channel is really "created". Is it when the genesis block is created or when nodes are joined to it or is it when enough nodes are joined to it. This is basically saying that, yes, a genesis block has been created, but the channel isn't really "active" until nodes are joined to it. Sort of splitting the difference.

Anyway, I think if we come to broader agreement about what terms to use in these situations that will be clear up what terminology should be used here and elsewhere.

Welcome better suggestions there.

docs/source/create_channel/create_channel_participation.md

jyellick · 2020-11-13T16:38:41Z

docs/source/create_channel/create_channel_participation.md

+
+Over time it may be necessary to add additional ordering nodes to the consenter set of a channel. Other organizations may want to contribute their own orderers to the cluster, or it might prove advantageous under production conditions to permit multiple orderers to go down for maintenance at the same time.
+
+Anytime a new orderer joins the cluster, you need to ensure that you do not lose quorum while the ledger on the new orderer catches up. Adding a fourth orderer to an existing three node cluster changes the majority from two to three. Therefore, during the catch-up process and until the new orderer starts executing consensus, the cluster is in a state of reduced fault tolerance. To account for this situation and avoid any downtime, a command that can ascertain the `consensusRelation` status of an orderer, which can be either "consenter" or "follower", has been introduced. When a node joins as a follower, the channel ledger is replicated from other orderers, but as it does not take part in consensus, channel operations are not impacted. Because replicating a long chain of blocks could take a long time, joining as a follower is useful for channels with high block heights. To join an orderer to a channel as a follower, **do not include the node in the channel configuration consenter set**.


Because replicating a long chain of blocks could take a long time, joining as a follower is useful for channels with high block heights.

I would say "is most useful". But it's generically useful because it allows you to confirm that an OSN is able to replicate blocks before having it count towards quorum. (You can imagine for instance, a network firewall rule which prevents the orderer from contacting the others being detectable in this way).

Good point. I changed it to
Because replicating a long chain of blocks could take a long time, joining as a follower is most useful for channels with high block heights because it allows you to confirm that an orderer is able to replicate blocks before having it count towards quorum.

pamandrejko

I also added a section about the osnadmin CLI command in the Using configtx.yaml to build a channel configuration topic.

pamandrejko · 2020-11-13T14:23:41Z

docs/source/create_channel/create_channel.md

@@ -1,4 +1,4 @@
-# Creating a new channel
+# Create a channel with a system channel (legacy)


Actually, I meant to add this to the docs/source/create_channel/create_channel_overview.rst topic too so users get a little guidance on which tutorial to pick and I forgot. So I'm grateful you brought this up. I've added a few lines to both topics now.

docs/source/create_channel/create_channel_participation.md

pamandrejko · 2020-11-13T17:56:32Z

docs/source/create_channel/create_channel_participation.md

+ * **Flexibility**: Whereas ordering nodes could only be part of a single ordering service, orderers can now join or leave channels as needed, similar to how peers can join any channel its organization is a member of.
+ * **Operational benefits**:
+    * Easy to list the channels that the ordering node is a consenter on.
+    * Simple process to delete a channel and the ledger associated with that channel.


Changed it to
* Simple process to remove a channel and the blocks associated with that channel.

pamandrejko · 2020-11-13T19:23:35Z

docs/source/create_channel/create_channel_participation.md

+
+Certificate names used in this example are for illustration purposes and may not reflect the actual names of the certificates generated by the CA. When you generate the certificates you can rename them accordingly to make it easier to differentiate them.
+
+**Important:** You need to create the `config.yaml` file in the orderer organization MSP and orderer local MSP. This file enables "Node OU" support for the channel, a feature that allows the channel to recognize certificates that contain the "admin" OU as representing organization admins (who are admins of the ordering nodes owned by the organization by default). Learn more in the [Fabric CA](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/deployguide/use_CA.html#nodeous) documentation.


Yes. The Node OU support is for both the organization msp on the channel, and for the local msp admin.
My understanding is that an ordering node admin (local MSP) really has no special privileges at all -- unlike a peer admin which is required to install a smart contract on a peer.

But we know that osnadmin client can join an orderer to a channel and remove it from the channel and list the channels that the orderer is a member of.

@denyeart Not sure if I've addressed your comment here? Perhaps there is something more you need me to clarify in the doc?

docs/source/create_channel/create_channel_participation.md

pamandrejko · 2020-11-13T19:39:49Z

docs/source/create_channel/create_channel_participation.md

+
+ * **System channel no longer required**: Besides the creation of the system representing an extra step (as compared to the new process), this system channel created an extra layer of administration that, for some use cases, provided no tangible benefit.
+ * **Consortium no longer required**: You no longer need to define the set of organizations, known as the "consortium", who are permitted to create channels on a particular ordering service. With this new process, **all channels are application channels**, so the concept of a list of organizations who can create channels no longer applies. Any set of organizations can get together and create a channel using a defined set of ordering nodes (which become the ordering service of that channel).
+ * **Simplified ordering node creation process**: Because a genesis block no longer needs to exist before an ordering node is created, admins can now focus on the process of setting up their infrastructure and making sure their node is working correctly before joining a particular application channel. Additionally, because an ordering node no longer needs to scan the system channel ledger to determine which channels it is joined to and then replicate those ledgers, the node starts up more rapidly.


Given he said it not really true. I removed it.

docs/source/create_channel/create_channel_participation.md

pamandrejko · 2020-11-13T19:45:04Z

docs/source/create_channel/create_channel_participation.md

+
+## Step two: Use the `osnadmin` CLI to start the channel
+
+Now that the genesis block has been created, the first ordering node that receives the `osnadmin channel join` command command effectively "activates" the channel, though the channel is not fully operational until a quorum of consenters is established (if your profile listed three consenters, at least one more node, for a total of two, would have to join using the `osnadmin channel join` command).


Welcome better suggestions there.

Signed-off-by: pama-ibm <pama@ibm.com> Edit to participation test Change-Id: Ib454d4cec1e0689ada82be3afe19bc5ba74e1412 Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> Signed-off-by: pama-ibm <pama@ibm.com> Edit to participation test Change-Id: Ib454d4cec1e0689ada82be3afe19bc5ba74e1412 Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> Signed-off-by: pama-ibm <pama@ibm.com> Edits to participation doc Change-Id: I6394400bf41152b9038c5d02ed3ac6c8f03dcd0f Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> More edits to participation doc Change-Id: Ic89bf533878431827605b0a91229862a0d267d0e Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> Edits for RFC language Change-Id: I087e756dfd9fadc721562bc2c3b00bf3408b0eb6 Signed-off-by: joe-alewine <Joe.Alewine@ibm.com> Signed-off-by: pama-ibm <pama@ibm.com>

denyeart · 2020-11-14T21:11:10Z

Nice doc, let's go ahead and merge, we can always tweak further in a subsequent PR.

denyeart · 2020-11-15T18:25:59Z

This PR was merged and then reverted due to a squash issue.
Ultimately the doc content was merged using subsequent PR #2127.

pamandrejko added the documentation label Nov 6, 2020

wlahti suggested changes Nov 6, 2020

View reviewed changes

pamandrejko force-pushed the FAB-18178 branch 3 times, most recently from 382f9e6 to c884838 Compare November 9, 2020 18:31

wlahti suggested changes Nov 9, 2020

View reviewed changes

wlahti reviewed Nov 9, 2020

View reviewed changes

docs/source/create_channel/create_channel_participation.md Show resolved Hide resolved

wlahti reviewed Nov 9, 2020

View reviewed changes

docs/source/create_channel/create_channel_participation.md Show resolved Hide resolved

pamandrejko force-pushed the FAB-18178 branch 3 times, most recently from 8a32c45 to 5eebe6a Compare November 11, 2020 15:22

pamandrejko marked this pull request as ready for review November 11, 2020 15:24

pamandrejko requested review from a team as code owners November 11, 2020 15:24

pamandrejko force-pushed the FAB-18178 branch from 5eebe6a to 80cb3c6 Compare November 11, 2020 16:40

pamandrejko force-pushed the FAB-18178 branch 3 times, most recently from d357edd to 68dcce1 Compare November 11, 2020 21:35

wlahti reviewed Nov 12, 2020

View reviewed changes

tock-ibm reviewed Nov 12, 2020

View reviewed changes

pamandrejko force-pushed the FAB-18178 branch from 68dcce1 to 9bffddf Compare November 12, 2020 21:27

denyeart reviewed Nov 13, 2020

View reviewed changes

jyellick reviewed Nov 13, 2020

View reviewed changes

pamandrejko commented Nov 13, 2020

View reviewed changes

pamandrejko force-pushed the FAB-18178 branch 2 times, most recently from a4863da to 8d01fe6 Compare November 13, 2020 20:07

pamandrejko force-pushed the FAB-18178 branch from 8d01fe6 to 523931f Compare November 14, 2020 20:23

denyeart approved these changes Nov 14, 2020

View reviewed changes

denyeart merged commit 40e845b into hyperledger:master Nov 14, 2020

This was referenced Nov 14, 2020

Revert "[FAB-18179] Channel Participation API tutorial" #2124

Merged

[FAB-18179] Channel Participation API Tutorial #2127

Merged


		## Step one: Generate the genesis block of the channel

		Channels are created by building a channel creation transaction, also referred to as the "genesis block", and submitting the transaction to the ordering service. The channel creation transaction specifies the initial configuration of the channel and is used by the ordering service to write the channel genesis block. While only one member needs to create the genesis block, it can be shared out of band with the other members on the channel who can inspect it to ensure they agree to the channel configuration and then used by each orderer.


		When successful, the channel is created with a ledger height `1`. Because this orderer is joining from the genesis block, the `status` is "active". And because the orderer is part of the channel consenter, its `consensusRelation` is "consenter". We delve more into the `consensusRelation` value in the next section.

		You can repeat the same command on the other two orderers. Because these two orderers join the channel from the genesis block and are part of the consenter set, their status transitions almost immediately from "onboarding" to "active" and the "consensusRelation" status is "consenter". At this point, the channel becomes operational because the default policy of a MAJORITY of consenters (as defined in the channel configuration) are "active".


		When successful, the channel is started with a ledger height `1`. Because this orderer is joining from the genesis block, the `status` is "active". And because the orderer is part of the channel's consenter set, its `consensusRelation` is "consenter". We delve more into the `consensusRelation` value in the next section.

		You can repeat the same command on the other two orderers. Remember to update the `OSN_TLS_SIGN_CERT` and `OSN_TLS_PRIVATE_KEY` environment variables to point to the certificates for the corresponding orderer. Because these two orderers join the channel from the genesis block and are part of the consenter set, their status transitions almost immediately from "onboarding" to "active" and the "consensusRelation" status is "consenter". At this point, the channel becomes operational because a majority of consenters (as defined in the channel configuration) are "active". You should see something similar to the following in your orderer logs:


		### Add or remove orderers from existing channels

		You can continue to use the `osnadmin channel join` and `osnadmin channel remove` commands to add and remove orderers on each channel according to your business needs.

		@@ -1,4 +1,4 @@
		# Creating a new channel
		# Create a channel with a system channel (legacy)


		```

		Note: For simplicity, this snippet assumes that the peers and orderers belong to the same organization `SampleOrg`. You can refer to the [sample config](https://github.com/hyperledger/fabric/blob/{BRANCH}/sampleconfig/configtx.yaml) for the full example. For a production deployment however, it is recommended that the peer and ordering nodes belong to separate organizations.


		## Step two: Use the `osnadmin` CLI to start the channel

		Now that the genesis block has been created, the first ordering node that receives the `osnadmin channel join` command command effectively "activates" the channel, though the channel is not fully operational until a quorum of consenters is established (if your profile listed three consenters, at least one more node, for a total of two, would have to join using the `osnadmin channel join` command).


		Over time it may be necessary to add additional ordering nodes to the consenter set of a channel. Other organizations may want to contribute their own orderers to the cluster, or it might prove advantageous under production conditions to permit multiple orderers to go down for maintenance at the same time.

		Anytime a new orderer joins the cluster, you need to ensure that you do not lose quorum while the ledger on the new orderer catches up. Adding a fourth orderer to an existing three node cluster changes the majority from two to three. Therefore, during the catch-up process and until the new orderer starts executing consensus, the cluster is in a state of reduced fault tolerance. To account for this situation and avoid any downtime, a command that can ascertain the `consensusRelation` status of an orderer, which can be either "consenter" or "follower", has been introduced. When a node joins as a follower, the channel ledger is replicated from other orderers, but as it does not take part in consensus, channel operations are not impacted. Because replicating a long chain of blocks could take a long time, joining as a follower is useful for channels with high block heights. To join an orderer to a channel as a follower, do not include the node in the channel configuration consenter set.


		Certificate names used in this example are for illustration purposes and may not reflect the actual names of the certificates generated by the CA. When you generate the certificates you can rename them accordingly to make it easier to differentiate them.

		Important: You need to create the `config.yaml` file in the orderer organization MSP and orderer local MSP. This file enables "Node OU" support for the channel, a feature that allows the channel to recognize certificates that contain the "admin" OU as representing organization admins (who are admins of the ordering nodes owned by the organization by default). Learn more in the [Fabric CA](https://hyperledger-fabric-ca.readthedocs.io/en/release-1.4/deployguide/use_CA.html#nodeous) documentation.

[FAB-18179] Channel Participation API tutorial #2081

[FAB-18179] Channel Participation API tutorial #2081

Conversation

pamandrejko commented Nov 6, 2020

Type of change

Description

Additional details

Related issues

Release Note

wlahti left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pamandrejko commented Nov 11, 2020

azure-pipelines bot commented Nov 11, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tock-ibm Nov 12, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

denyeart left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyellick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pamandrejko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

denyeart commented Nov 14, 2020

denyeart commented Nov 15, 2020

tock-ibm Nov 12, 2020 •

edited