[FAB-17270] Create a channel tutorial part2

[nikhil550]

Signed-off-by: NIKHIL E GUPTA negupta@us.ibm.com

Type of change

• Documentation update

Description

The create a channel tutorial as a series of tutorials. This draft PR offers the second two in the series for review

[pamandrejko]

As usual Nik, you lay it all out nicely and make it feel straightforward.
I've read through it but would still like to run through all the commands and try it out.

[nikhil550]

Going to take the draft tag off of this, though will need lots more comment before we can merge. We may want to merge this series one at a time if it is easier.

[lindluni]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[pamandrejko]

Loving the new policy diagrams

[pamandrejko]

Really excellent piece of work here. A few comments throughout.

The only other thing I would mention is would it be worth breaking the Policies piece of this topic into a 3rd section of the tutorial? There's a clear delineation in the content here and that would make it overall shorter to read through each one separately.
But not required.

[pamandrejko]

While an organization can select their anchor peers on the channel for the first time using the configtxgen tool, it is recommended that each organization set anchor peers by using the configtxlator tool to update the channel configuration

I thought the peers had to be joined to the channel first before they can be made an anchor peer?

[nikhil550]

That detail is provided in the other tutorial: https://hyperledger-fabric.readthedocs.io/en/latest/create_channel/create_channel.html#set-anchor-peers
After an organizations has joined their peers to the channel, they should select at least one of their peers to become an anchor peer

[pamandrejko]

Suggestion: These policies govern the number of [peer] organizations that need to approve a chaincode definition or sign a request to update the channel configuration.

[nikhil550]

done

[pamandrejko]

Suggestion: I would insert a simple heading here: TwoOrgsOrdererGenesis and then another further down (line 157) when you switch to the second profile to TwoOrgsChannel for the reader to more easily switch gears.

[nikhil550]

done.

[pamandrejko]

Nicely said!

[pamandrejko]

The TwoOrgsChannel provides [the] name of the SampleConsortium..
or
The TwoOrgsChannel includes the SampleConsortium that was defined in the system channel.

[pamandrejko]

Should we call out that the Application section is unique to/only required for application channels?

[nikhil550]

On the second point, I think that is self evident. I still think people will still use the examples very closely, but just have more context now.

[pamandrejko]

As [an] example,
For example,

[nikhil550]

Done.

[pamandrejko]

if they if the can satisfy the

[nikhil550]

done.

[pamandrejko]

These diagrams are really helpful. One thing that occurred to me is that if we included examples of the signature policies in the right column, they would tie all this together.

So for example in this diagram, instead of in the Org1 box where you have Writers, we could have
Writers "OR('Org1MSP.admin', 'Org1MSP.client')"

Just an idea. I know that could be alot of work and might clutter up your diagrams, but for me it visually ties the ImplicitMeta and Signature policies together.

[nikhil550]

I like the idea, but I think it would get awfully busy, so I will leave for now.

[pamandrejko]

I like your usage of the light green checkmark to visually convey this concept.

[pamandrejko]

After reading the entire topic I came back to this section. I think it deserves more focus. Maybe a heading like Purpose of this tutorial or something like that.

I love how you take apart and explain each element in each section - very well done. I was not prepared for that when I started reading this topic. Would it benefit from links here to each section below? I'm torn because I think it is useful to read from top to bottom to understand it all and more importantly how the Profiles section uses the content from the other sections. But when I come back later and want to re-read a section it might be nice to have a link directly to the portion of the file that I am interested in. Maybe it will already be there in the left toc? Certainly not a requirement but a nice to have.

[nikhil550]

I will put an overview heading after the first two paragraphs to break up the text. A list of sections of links wont either, and will help tie the channel policies together as a section.

[jyellick]

Each channel member is associated with a set of signature policies

This is technically correct, in that you could create a mapping from channel member to signature policies which include them, but this is a really very weird way to look at it to me. Rather, signature policies reference channel members, rather than the other way around.

Signature policies read the digital signatures that are attached to the transactions or channel update requests that are submitted to the channel.

I don't mean to be pedantic, but policies do not read signatures. Fabric (the peer or the orderer) reads signatures from some structure, be it a transaction, a proposal, a deliver request, a block, a service discovery request, what have you. The signatures which Fabric reads are then given as a parameter to a policy, and the policy evaluates that set of signatures to determine if they satisfy the policy.

While I'm being overly pedantic, I'll add that "signature policies" are poorly named. All of the policies are actually evaluated over identities, and identities are validated by signature. The name was chosen before design was completed and we thought there would be other types of data a policy might evaluate over, but that never happened. I don't think it's appropriate to add this confusion to the doc, but wanted to share.

[nikhil550]

Replacing this paragraph with the following: By default, each channel member defines a set of signature policies that references their organization. When a transaction or channel update request is submitted to the peer and ordering nodes on the channel channel, the nodes read the signatures attached to the transaction and evaluate them against the signature policies defined in the channel configuration. Every signature policy has rule that specifies the set of organizations and identities whose signatures can satisfy the policy.

[jyellick]

Org1 is associated with four signature policies.

Same language problem here. Org1 defines four signature policies. It may be referenced or associated with other signature policies in the system.

The Admins policy can only be satisfied by the transactions submitted by an identity with an admin role, while only identities with a peer role can satisfy the Endorsement policy.

You say transactions for admins, but identities for endorsement. 'identities' is correct for both.

Each transaction can satisfy multiple signature policies. For example, if a transaction submitted to eh channel was endorsed by a peer from Org1 and Org2, the transaction would satisfy the Endorsement signature policy that is associated with both Org1 and Org2.

I would say "A single signature set may satisfy multiple signature policies. For example, if the endorsements attached to a transaction were provided by both Org1 and Org2, then this signature set would satisfy the 'Endorsement' policy of Org1 and Org2.

[nikhil550]

Replacing the paragraph with the following: All the policies above can be satisfied by signatures from Org1. However, each policy lists a different set of roles from within the organization that are able to satisfy the policy. The Adminspolicy can only be satisfied by the transactions submitted by an identity with an admin role, while only identities with a peer role can satisfy the Endorsement policy. A set of signatures attached to a single transaction can satisfy multiple signature policies. For example, if the endorsements attached to a transaction were provided by both Org1 and Org2, then this signature set would satisfy theEndorsement policy of Org1 and Org2.

[jyellick]

It's hard for me to read whether the language is all referring only to the sample configtx.yaml here, or whether it's talking more broadly about policies. I would say that "In the default" or "In the sample" configtx.yaml, the signature policies of each organization are evaluated by ImplicitMeta policies at higher levels of the channel configuration.

For instance, if you set a signature policy at the application level for /Channel/Application/Readers, then the /Channel/Application/Org*/Readers policies are no longer used for anything.

Instead of directly reading the signatures that are submitted to the channel, ImplicitMeta policies read other policies in the channel configuration.

Same issue above about 'reading', policies are handed signature sets (or, identity sets really) and evaluated. In the ImplicitMeta case, these policies evaluate policies defined more deeply in the channel config tree, but if anything, the sort of verb being done to the signature set and the sort of verb being done to the sub-policies strikes me as different.

An ImplicitMeta policies is satisfied if a transaction satisfies the signature policies that are referenced by that policy.

Well, the ImplicitMeta policy has a Rule, which indicates how many of the sub-policies (which may be signature policies, or may be more implicit meta policies) must be satisfied. Notably 'All', 'Any', or 'Majority'.

[nikhil550]

The article is about the default policies work, with understanding that once users have the background they need, they can change them. I added this sentence to the opening: If you use the default policies used by the Fabric test network or the Fabric sample configuration, each channel you create will use a combination of signature policies, ImplicitMeta policies, and Access Control Lists to determine how organizations interact with the channel and agree to update the channel structure.`

I also updated the ImplictMeta paragraph in response to your comments: If your channel uses the default policies, the signature policies for each organization are evaluated by ImplicitMeta policies at higher levels of the channel configuration. Instead of directly evaluating the signatures that are submitted to the channel, ImplicitMeta policies have rules specify a set of other policies in the channel configuration that can satisfy the policy. A transaction can satisfy an ImplicitMeta policy if it can satisfy the underlying set of signature policies that are referenced by the policy.

[jyellick]

Again, it's satisfied by any majority of the Admins signature policies of the organizations. It's common (and typical) that an implicit policy will not satisfy all of the sub-policies (unless the rule 'All' is used, which, we don't use as a default anywhere).

[nikhil550]

Updated caption: Figure 1: The Admins ImplicitMeta policy can be satisfied by a majority of the Admins signature policies that are defined by each organization.

[jyellick]

For better, or perhaps for worse, it's not simply every group, but every item. So, adding an organization is 'modifying the membership of the application group', so triggers that group's mod policy. On the other hand, modifying the ACLs of the application group is simply modifying one of the group's values, and not the group itself, so in this case, the mod policy of the ACLs is checked.

This is a bit of a headache because it means there are tons of permutations, which is why we default (almost) all of the mod policies to be simply 'Admins'. Since this is read as a relative path, this implies the 'Admins' policy of the containing group. But, you can, and we see users who do, modify this to point to explicit policies. For instance, the orderer admins may set the /Channel/Orderer/BatchTimeout value's mod_policy to be "/Channel/Application/Admins" so as to give up control over the batch timeout to the application admins.

[nikhil550]

Updating the first paragraph: Each component of the channel configuration has a modification policy that needs to be satisfied in order to be updated by channel members. For example, the policies and channel MSP defined by each organization, the application group that contains the members of the channel, and the components of the configuration that define the channel consenter set each have a different modification policy.

Again, I think i will leave the changes that more advanced users can make to the reader, or to other tutorials.

[jyellick]

This doesn't make sense to me. I would say:

The Channel/Orderer/BlockValidation policy is used by peers when receiving blocks (either from ordering, or via gossip). The peers check that the signature set attesting to the block's validity satisfies the block validation policy to confirm that the block was generated by ordering. By default, any ordering org 'Writers' are authorized to attest to a block's validity.

[nikhil550]

An edited version of your suggestion: The `Channel/Orderer/BlockValidation` policy is used by peers to confirm that new blocks being added to the channel were generated by an ordering node that is part of the channel consenter set, and that the block was not tampered with or created by another peer organization. By default, any orderer organization with a `writers` signature policy can create and validate blocks for the channel.

[jyellick]

Thanks for the updates @nikhil550 looks much better. Found a few typos or minor things in the new text. We can always merge as is, or fix them here, up to you.

[jyellick]

Typo: "channel channel"

When a transaction or channel update request is submitted to the peer and ordering nodes

Maybe: When a proposal is submitted to a peer, or a transaction is submitted to the ordering nodes

My concern is confusion caused by this sentence implying that config updates are submitted to peers -- they are not.

[nikhil550]

channel channel
Removed.

[nikhil550]

Going to use your suggestion: When a proposal is submitted to a peer, or a transaction is submitted to the ordering nodes.

[jyellick]

The Admins policy can only be satisfied by the transactions submitted by an identity

Typo, I think? Should say "satisfied by transactions", not "satisfied by the transactions". Though I might opt simply to change this to "satisfied by an identity" like is done for the Endorsement policy in the second half of the sentence.

Also, Admins is monospace code, but Endorsement is not.

[nikhil550]

Going to say: The Admins policy can only be satisfied by transactions submitted by an identity with an admin role, while only identities with a peer role can satisfy the Endorsement policy.

By transactions seems redundant, but I think will help keep things grounded for more users.

[jyellick]

Small typo: writers instead of Writers.

[nikhil550]

Done.

changes addressed.

[jyellick]

LGTM

[nikhil550]

@Mergifyio backport release-2.1

[mergify]

Command backport release-2.1: success

Backports have been created

• #1420 [FAB-17270] Create a channel tutorial part2 (bp #1105) has been created for branch release-2.1