github.com/yacovm/fabric@v2.0.0-alpha.0.20191128145320-c5d4087dc723+incompatible/docs/source/capabilities_concept.md

github.com/yacovm/fabric@v2.0.0-alpha.0.20191128145320-c5d4087dc723+incompatible/docs/source/capabilities_concept.md (about)

1 # Channel capabilities
2
3 **Audience**: Channel administrators, node administrators
4
5 *Note: this is an advanced Fabric concept that is not necessary for new
6 users or application developers to understand. However, as channels and
7 networks mature, understanding and managing capabilities becomes vital.
8 Furthermore, it is important to recognize that updating capabilties is a
9 different, though often related, process to upgrading nodes. We'll describe
10 this in detail in this topic.*
11
12 Because Fabric is a distributed system that will usually involve multiple
13 organizations, it is
14 possible (and typical) that different versions of Fabric code will exist on
15 different nodes within the network as well as on the channels in that network.
16 Fabric allows this --- it is not necessary for every peer and ordering node to
17 be at the same version level. In fact, supporting different version levels
18 is what enables rolling upgrades of Fabric nodes.
19 What **is** important is that networks and channels
20 process things in the same way, creating deterministic results for things like
21 channel configuration updates and chaincode invocations. Without deterministic
22 results, one peer on a channel might invalidate a transaction while another peer
23 may validate it.
24
25 To that end, Fabric defines levels of what are called "capabilities". These
26 capabilities, which are defined in the configuration of each channel, ensure
27 determinism by defining a level at which behaviors produce consistent results.
28 As you'll see, these capabilities have versions which are closely related to
29 node binary versions. Capabilities enable nodes running at different version
30 levels to behave in a compatible and consistent way given the channel
31 configuration at a specific block height. You will also see that capabilities
32 exist in many parts of the configuration tree, defined along the lines of
33 administration for particular tasks.
34
35 As you'll see, sometimes it is necessary to update your channel to a new
36 capability level to enable a new feature.
37
38 ## Node versions and capability versions
39
40 If you're familiar with Hyperledger Fabric, you're aware that it follows the
41 typical semantic versioning pattern: v1.1, v1.2.1, etc. These versions refer to
42 releases and their related binary versions.
43
44 Capabilities follow the same semantic versioning convention. There are v1.1
45 capabilities and v1.2 capabilities and so on. But it's important to note a few
46 distinctions.
47
48 * **There is not necessarily a new capability level with each release**.
49 The need to establish a new capability is determined on a case by case basis
50 and relies chiefly on the backwards compatibility of new features and older
51 binary versions. Adding Raft ordering services in v1.4.1, for example, did not
52 change the way either transactions or ordering service functions were handled
53 and thus did not require the establishment of any new capabilities.
54 [Private Data](./private-data/private-data.html), on the other hand, could not
55 be handled by peers before v1.2, requiring the establishment of a v1.2
56 capability level. Because not every release contains a new feature (or a bug
57 fix) that changes the way transactions are processed, certain releases will not
58 require any new capabilities (for example, v1.4) while others will only have new
59 capabilities at particular levels (such as v1.2 and v1.3). We'll discuss the
60 "levels" of capabilities and where they reside in the configuration tree later.
61
62
63 * **Nodes must be at least at the level of certain capabilities in a channel**.
64 When a peer joins a channel, it reads all of the blocks in the ledger sequentially,
65 starting with the genesis block of the channel and continuing through the
66 transaction blocks and any subsequent configuration blocks. If a node,
67 for example a peer, attempts to read a block containing an update to a
68 capability it doesn't understand (for example, a v1.2 peer trying to read
69 a block with a v1.4.2 application capability), **the peer will crash**. This
70 crashing behavior is intentional, as a v1.2 peer cannot validate or commit any
71 transactions past this point. Before joining a channel, **make sure the node is
72 at the Fabric version (binary) level of the capabilities specified in the
73 channel config relevant to the node or higher**. We'll discuss which
74 capabilities are relevant to which nodes later. However, because no user wants
75 their nodes to crash, it is strongly recommended to update all nodes to the
76 required level (preferably, to the latest release) before attempting to update
77 capabilities. This is in line with the default Fabric recommendation to
78 **always** be at the latest binary and capability levels.
79
80 If users are unable to upgrade their binaries, then capabilities must be left at
81 their lower levels. Lower level binaries and capabilities will still work
82 together as they're meant to. However, keep in mind that it is a best practice
83 to always update to new binaries even if a user chooses not to update their
84 capabilities. Because capabilities themselves also include bug-fixes, it is
85 always recommended to update capabilities once the network binaries support them.
86
87 ## Capability configuration groupings
88
89 As we discussed earlier, there is not a single capability level encompassing an
90 entire channel. Rather, there are three capabilities, each representing an area of
91 administration.
92
93 * **Orderer**: These capabilities govern tasks and processing exclusive to the
94 ordering service. Because these capabilities do not involve processes that
95 affect transactions or the peers, updating them falls solely to the ordering
96 service admins (peers do not need to understand orderer capabilities and will
97 therefore not crash no matter what the orderer capability is updated to). Note
98 that these capabilities did not change between v1.1 and v1.4.2. However, as
99 we'll see in the **channel** section, this does not mean that v1.1 ordering
100 nodes will work on all channels with capability levels below v1.4.2.
101
102 * **Application**: These capabilities govern tasks and processing exclusive to
103 the peers. Because ordering service admins have no role in deciding the nature
104 of transactions between peer organizations, changing this capability level
105 falls exclusively to peer organizations. For example, Private Data can only be
106 enabled on a channel with the v1.2 application group capability (or higher)
107 enabled. In the case of Private Data, this is the only capability that must be
108 enabled, as nothing about the way Private Data works requires a change to
109 channel administration or the way the ordering service processes transactions.
110
111 * **Channel**: This grouping encompasses tasks that are **jointly administered**
112 by the peer organizations and the ordering service. For example, this is the
113 capability that defines the level at which channel configuration updates, which
114 are initiated by peer organizations and orchestrated by the ordering service, are
115 processed. On a practical level, **this grouping defines the minimum level for
116 all of the binaries in a channel, as both ordering nodes and peers must be at
117 least at the binary level corresponding to this capability in order to process
118 the capability**.
119
120 The **orderer** and **channel** capabilities of a channel are inherited by
121 default from the ordering system channel, where modifying them are the exclusive
122 purview of ordering service admins. As a result, peer organizations should
123 inspect the genesis block of a channel prior to joining their peers to that
124 channel. Although the channel capability is administered by the orderers in the
125 orderer system channel (just as the consortium membership is), it is typical and
126 expected that the ordering admins will coordinate with the consortium admins to
127 ensure that the channel capability is only upgraded when the consortium is ready
128 for it.
129
130 Because the ordering system channel does not define an **application**
131 capability, this capability must be specified in the channel profile when
132 creating the genesis block for the channel. For more information about creating
133 the genesis block of a channel, check out [configtx](configtx.html).
134
135 **Take caution** when specifying or modifying an application capability. Because
136 the ordering service does not validate that the capability level is valid, it will
137 allow a channel to be created (or modified) to contain, for example, a v1.8
138 application capability even if no such capability exists. Any peer attempting to
139 read a configuration block with this capability would, as we have shown, crash,
140 and even if it was possible to modify the channel once again to a valid capability,
141 it would not matter, as no peer would be able to get past the block with the
142 invalid v1.8 capability.
143
144 For a full look at the current valid orderer, application, and channel capabilities
145 check out a [sample `configtx.yaml` file](http://github.com/hyperledger/fabric/blob/master/sampleconfig/configtx.yaml),
146 which lists them in the "Capabilities" section.
147
148 For more specific information about capabilities and where they reside in the channel
149 configuration, check out [defining capability requirements](capability_requirements.html).
150
151