[FAB-15979] Improve capabilities documentation

joe-alewine · denyeart · commit 168df2cb125e · 2019-08-09T18:01:18.000Z
Created new "key concept" capabilities doc.

Moved existing capabilities doc to Ops Guide
(where it probably always belonged)

Change-Id: Ic16baf0e30066121f0b4f2d0e8c5b047680fff1c
Signed-off-by: joe-alewine &lt;Joe.Alewine@ibm.com&gt;
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -10,7 +10,6 @@ Architecture Reference
    fabric-sdks
    discovery-overview
    channels
-   capability_requirements
    couchdb_as_state_database
    peer_event_services
    private-data-arch
diff --git a/docs/source/capabilities_concept.md b/docs/source/capabilities_concept.md
@@ -0,0 +1,152 @@
+# Channel capabilities
+
+**Audience**: Channel administrators, node administrators
+
+*Note: this is an advanced Fabric concept that is not necessary for new
+users or application developers to understand. However, as channels and
+networks mature, understanding and managing capabilities becomes vital.
+Furthermore, it is important to recognize that updating capabilties is a
+different, though often related, process to upgrading nodes. We'll describe
+this in detail in this topic.*
+
+Because Fabric is a distributed system that will usually involve multiple
+organizations, it is
+possible (and typical) that different versions of Fabric code will exist on
+different nodes within the network as well as on the channels in that network.
+Fabric allows this --- it is not necessary for every peer and ordering node to
+be at the same version level. In fact, supporting different version levels
+is what enables rolling upgrades of Fabric nodes. 
+What **is** important is that networks and channels
+process things in the same way, creating deterministic results for things like
+channel configuration updates and chaincode invocations. Without deterministic
+results, one peer on a channel might invalidate a transaction while another peer
+may validate it.
+
+To that end, Fabric defines levels of what are called "capabilities". These
+capabilities, which are defined in the configuration of each channel, ensure
+determinism by defining a level at which behaviors produce consistent results.
+As you'll see, these capabilities have versions which are closely related to
+node binary versions. Capabilities enable nodes running at different version
+levels to behave in a compatible and consistent way given the channel
+configuration at a specific block height. You will also see that capabilities
+exist in many parts of the configuration tree, defined along the lines of
+administration for particular tasks.
+
+As you'll see, sometimes it is necessary to update your channel to a new
+capability level to enable a new feature.
+
+## Node versions and capability versions
+
+If you're familiar with Hyperledger Fabric, you're aware that it follows the
+typical semantic versioning pattern: v1.1, v1.2.1, etc. These versions refer to
+releases and their related binary versions.
+
+Capabilities follow the same semantic versioning convention. There are v1.1
+capabilities and v1.2 capabilities and so on. But it's important to note a few
+distinctions.
+
+* **There is not necessarily a new capability level with each release**.
+  The need to establish a new capability is determined on a case by case basis
+  and relies chiefly on the backwards compatibility of new features and older
+  binary versions. Adding Raft ordering services in v1.4.1, for example, did not
+  change the way either transactions or ordering service functions were handled
+  and thus did not require the establishment of any new capabilities.
+  [Private Data](./private-data/private-data.html), on the other hand, could not
+  be handled by peers before v1.2, requiring the establishment of a v1.2
+  capability level. Because not every release contains a new feature (or a bug
+  fix) that changes the way transactions are processed, certain releases will not
+  require any new capabilities (for example, v1.4) while others will only have new
+  capabilities at particular levels (such as v1.2 and v1.3). We'll discuss the
+  "levels" of capabilities and where they reside in the configuration tree later.
+
+
+* **Nodes must be at least at the level of certain capabilities in a channel**.
+  When a peer joins a channel, it reads all of the blocks in the ledger sequentially,
+  starting with the genesis block of the channel and continuing through the
+  transaction blocks and any subsequent configuration blocks. If a node,
+  for example a peer, attempts to read a block containing an update to a
+  capability it doesn't understand (for example, a v1.2 peer trying to read
+  a block with a v1.4.2 application capability), **the peer will crash**. This
+  crashing behavior is intentional, as a v1.2 peer cannot validate or commit any
+  transactions past this point. Before joining a channel, **make sure the node is
+  at the Fabric version (binary) level of the capabilities specified in the
+  channel config relevant to the node or higher**. We'll discuss which
+  capabilities are relevant to which nodes later. However, because no user wants
+  their nodes to crash, it is strongly recommended to update all nodes to the
+  required level (preferably, to the latest release) before attempting to update
+  capabilities. This is in line with the default Fabric recommendation to
+  **always** be at the latest binary and capability levels.
+
+If users are unable to upgrade their binaries, then capabilities must be left at
+their lower levels. Lower level binaries and capabilities will still work
+together as they're meant to. However, keep in mind that it is a best practice
+to always update to new binaries even if a user chooses not to update their
+capabilities. Because capabilities themselves also include bug-fixes, it is
+always recommended to update capabilities once the network binaries support them.
+
+## Capability configuration groupings
+
+As we discussed earlier, there is not a single capability level encompassing an
+entire channel. Rather, there are three capabilities, each representing an area of
+administration.
+
+* **Orderer**: These capabilities govern tasks and processing exclusive to the
+  ordering service. Because these capabilities do not involve processes that
+  affect transactions or the peers, updating them falls solely to the ordering
+  service admins (peers do not need to understand orderer capabilities and will
+  therefore not crash no matter what the orderer capability is updated to). Note
+  that these capabilities did not change between v1.1 and v1.4.2. However, as
+  we'll see in the **channel** section, this does not mean that v1.1 ordering
+  nodes will work on all channels with capability levels below v1.4.2.
+
+* **Application**: These capabilities govern tasks and processing exclusive to
+  the peers. Because ordering service admins have no role in deciding the nature
+  of transactions between peer organizations, changing this capability level
+  falls exclusively to peer organizations. For example, Private Data can only be
+  enabled on a channel with the v1.2 application group capability (or higher)
+  enabled. In the case of Private Data, this is the only capability that must be
+  enabled, as nothing about the way Private Data works requires a change to
+  channel administration or the way the ordering service processes transactions.
+
+* **Channel**: This grouping encompasses tasks that are **jointly administered**
+  by the peer organizations and the ordering service. For example, this is the
+  capability that defines the level at which channel configuration updates, which
+  are initiated by peer organizations and orchestrated by the ordering service, are
+  processed. On a practical level, **this grouping defines the minimum level for
+  all of the binaries in a channel, as both ordering nodes and peers must be at
+  least at the binary level corresponding to this capability in order to process
+  the capability**.
+
+The **orderer** and **channel** capabilities of a channel are inherited by
+default from the ordering system channel, where modifying them are the exclusive
+purview of ordering service admins. As a result, peer organizations should
+inspect the genesis block of a channel prior to joining their peers to that
+channel. Although the channel capability is administered by the orderers in the
+orderer system channel (just as the consortium membership is), it is typical and
+expected that the ordering admins will coordinate with the consortium admins to
+ensure that the channel capability is only upgraded when the consortium is ready
+for it.
+
+Because the ordering system channel does not define an **application**
+capability, this capability must be specified in the channel profile when
+creating the genesis block for the channel. For more information about creating
+the genesis block of a channel, check out [configtx](configtx.html).
+
+**Take caution** when specifying or modifying an application capability. Because
+the ordering service does not validate that the capability level is valid, it will
+allow a channel to be created (or modified) to contain, for example, a v1.8
+application capability even if no such capability exists. Any peer attempting to
+read a configuration block with this capability would, as we have shown, crash,
+and even if it was possible to modify the channel once again to a valid capability,
+it would not matter, as no peer would be able to get past the block with the
+invalid v1.8 capability.
+
+For a full look at the current valid orderer, application, and channel capabilities
+check out a [sample `configtx.yaml` file](http://github.com/hyperledger/fabric/blob/master/sampleconfig/configtx.yaml),
+which lists them in the "Capabilities" section.
+
+For more specific information about capabilities and where they reside in the channel
+configuration, check out [defining capability requirements](capability_requirements.html).
+
+<!--- Licensed under Creative Commons Attribution 4.0 International License
+https://creativecommons.org/licenses/by/4.0/ -->
diff --git a/docs/source/capability_requirements.rst b/docs/source/capability_requirements.rst
@@ -1,33 +1,10 @@
-Capability Requirements
------------------------
-
-Because Fabric is a distributed system that will usually involve multiple
-organizations (sometimes in different countries or even continents), it is
-possible (and typical) that many different versions of Fabric code will exist in
-the network. Nevertheless, it’s vital that networks process transactions in the
-same way so that everyone has the same view of the current network state.
-
-This means that every network -- and every channel within that network – must
-define a set of what we call “capabilities” to be able to participate in
-processing transactions. For example, Fabric v1.1 introduces new MSP role types
-of “Peer” and “Client”. However, if a v1.0 peer does not understand these new
-role types, it will not be able to appropriately evaluate an endorsement policy
-that references them. This means that before the new role types may be used, the
-network must agree to enable the v1.1 ``channel`` capability requirement,
-ensuring that all peers come to the same decision.
-
-Only binaries which support the required capabilities will be able to participate in the
-channel, and newer binary versions will not enable new validation logic until the
-corresponding capability is enabled.  In this way, capability requirements ensure that
-even with disparate builds and versions, it is not possible for the network to suffer a
-state fork.
-
-Defining Capability Requirements
+Defining capability requirements
 ================================
 
-Capability requirements are defined per channel in the channel configuration (found
-in the channel’s most recent configuration block). The channel configuration contains
-three locations, each of which defines a capability of a different type.
+As discussed in :doc:`capabilities_concept`, capability requirements are defined
+per channel in the channel configuration (found in the channel’s most recent
+configuration block). The channel configuration contains three locations, each
+of which defines a capability of a different type.
 
 +------------------+-----------------------------------+----------------------------------------------------+
 | Capability Type  | Canonical Path                    | JSON Path                                          |
@@ -40,51 +17,20 @@ three locations, each of which defines a capability of a different type.
 |                  |                                   | Capabilities                                       |
 +------------------+-----------------------------------+----------------------------------------------------+
 
-* **Channel:** these capabilities apply to both peer and orderers and are located in
-  the root ``Channel`` group.
-
-* **Orderer:** apply to orderers only and are located in the ``Orderer`` group.
-
-* **Application:** apply to peers only and are located in the ``Application`` group.
-
-The capabilities are broken into these groups in order to align with the existing
-administrative structure. Updating orderer capabilities is something the ordering orgs
-would manage independent of the application orgs. Similarly, updating application
-capabilities is something only the application admins would manage. By splitting the
-capabilities between "Orderer" and "Application", a hypothetical network could run a
-v1.6 ordering service while supporting a v1.3 peer application network.
-
-However, some capabilities cross both the ‘Application’ and ‘Orderer’ groups. As we
-saw earlier, adding a new MSP role type is something both the orderer and application
-admins agree to and need to recognize. The orderer must understand the meaning
-of MSP roles in order to allow the transactions to pass through ordering, while
-the peers must understand the roles in order to validate the transaction. These
-kinds of capabilities -- which span both the application and orderer components
--- are defined in the top level "Channel" group.
-
-.. note:: It is possible that the channel capabilities are defined to be at version
-          v1.3 while the orderer and application capabilities are defined to be at
-          version 1.1 and v1.4, respectively. Enabling a capability at the "Channel"
-          group level does not imply that this same capability is available at the
-          more specific "Orderer" and "Application" group levels.
-
 Setting Capabilities
-====================
+--------------------
 
 Capabilities are set as part of the channel configuration (either as part of the
 initial configuration -- which we'll talk about in a moment -- or as part of a
 reconfiguration).
 
-.. note:: We have a two documents that talk through different aspects of channel
-          reconfigurations. First, we have a tutorial that will take you through
-          the process of :doc:`channel_update_tutorial`. And we also have a document that
-          talks through :doc:`config_update` which gives an overview of the
-          different kinds of updates that are possible as well as a fuller look
-          at the signature process.
+.. note:: For a tutorial that shows how to update a channel configuration, check
+          out :doc:`channel_update_tutorial`. For an overview of the different
+          kinds of channel updates that are possible, check out :doc:`config_update`.
 
-Because new channels copy the configuration of the Orderer System Channel by
+Because new channels copy the configuration of the ordering system channel by
 default, new channels will automatically be configured to work with the orderer
-and channel capabilities of the Orderer System Channel and the application
+and channel capabilities of the ordering system channel and the application
 capabilities specified by the channel creation transaction. Channels that already
 exist, however, must be reconfigured.
 
diff --git a/docs/source/key_concepts.rst b/docs/source/key_concepts.rst
@@ -15,4 +15,5 @@ Key Concepts
    ledger/ledger.md
    orderer/ordering_service.md
    private-data/private-data.md
+   capabilities_concept.md
    usecases
diff --git a/docs/source/ops_guide.rst b/docs/source/ops_guide.rst
@@ -9,6 +9,7 @@ Operations Guides
    config_update
    msp
    configtx
+   capability_requirements
    endorsement-policies
    token/FabToken
    pluggable_endorsement_and_validation
