diff --git a/docs/source/enable_cc_lifecycle.md b/docs/source/enable_cc_lifecycle.md deleted file mode 100644 index a4d55c1763b..00000000000 --- a/docs/source/enable_cc_lifecycle.md +++ /dev/null @@ -1,219 +0,0 @@ -# Enabling the new chaincode lifecycle - -Users upgrading from v1.4.x to v2.x will have to edit their channel configurations to enable the new lifecycle features. This process involves a series of [channel configuration updates](./config_update.html) the relevant users will have to perform. - -Note that the `Channel` and `Application` [capabilities](./capabilities_concept.html) of your application channels will have to be updated to `V2_0` for the new chaincode lifecycle to work. Check out [Considerations for getting to 2.0](./upgrade_to_newest_version.html#chaincode-lifecycle) for more information. - -Updating a channel configuration is, at a high level, a three step process (for each channel): - -1. Get the latest channel config -2. Create a modified channel config -3. Create a config update transaction - -We will be performing these channel configuration updates by leveraging a file called `enable_lifecycle.json`, which contains all of the updates we will be making in the channel configurations. Note that in a production setting it is likely that multiple users would be making these channel update requests. However, for the sake of simplicity, we are presenting all of the updates as how they would appear in a single file. - -## Create `enable_lifecycle.json` - -Note that in addition to using `enable_lifecycle.json`, this tutorial also uses `jq` to apply the edits to the modified config file. The modified config can also be edited manually (after it has been pulled, translated, and scoped). Check out this [sample channel configuration](./config_update.html#sample-channel-configuration) for reference. - -However, the process described here (using a JSON file and a tool like `jq`) does have the advantage of being scriptable, making it suitable for proposing configuration updates to a large number of channels, and is the recommended process for editing a channel configuration. - -Note that the `enable_lifecycle.json` uses sample values, for example `org1Policies` and the `Org1ExampleCom`, which will be specific to your deployment): - -``` -{ - "org1Policies": { - "Endorsement": { - "mod_policy": "Admins", - "policy": { - "type": 1, - "value": { - "identities": [ - { - "principal": { - "msp_identifier": "Org1ExampleCom", - "role": "PEER" - }, - "principal_classification": "ROLE" - } - ], - "rule": { - "n_out_of": { - "n": 1, - "rules": [ - { - "signed_by": 0 - } - ] - } - }, - "version": 0 - } - }, - "version": "0" - } - }, - "org2Policies": { - "Endorsement": { - "mod_policy": "Admins", - "policy": { - "type": 1, - "value": { - "identities": [ - { - "principal": { - "msp_identifier": "Org2ExampleCom", - "role": "PEER" - }, - "principal_classification": "ROLE" - } - ], - "rule": { - "n_out_of": { - "n": 1, - "rules": [ - { - "signed_by": 0 - } - ] - } - }, - "version": 0 - } - }, - "version": "0" - } - }, - "appPolicies": { - "Endorsement": { - "mod_policy": "Admins", - "policy": { - "type": 3, - "value": { - "rule": "MAJORITY", - "sub_policy": "Endorsement" - } - }, - "version": "0" - }, - "LifecycleEndorsement": { - "mod_policy": "Admins", - "policy": { - "type": 3, - "value": { - "rule": "MAJORITY", - "sub_policy": "Endorsement" - } - }, - "version": "0" - } - }, - "acls": { - "_lifecycle/CheckCommitReadiness": { - "policy_ref": "/Channel/Application/Writers" - }, - "_lifecycle/CommitChaincodeDefinition": { - "policy_ref": "/Channel/Application/Writers" - }, - "_lifecycle/QueryChaincodeDefinition": { - "policy_ref": "/Channel/Application/Writers" - }, - "_lifecycle/QueryChaincodeDefinitions": { - "policy_ref": "/Channel/Application/Writers" - } - } -} -``` - -**Note: the "role" field of these new policies should say `'PEER'` if [NodeOUs](./msp.html#organizational-units) are enabled for the org, and `'MEMBER'` if they are not.** - -## Edit the channel configurations - -To fully enable the new chaincode lifecycle, you must first edit the configuration of your own organization as it exists in a channel configuration, and then you must update the channel itself to include a default endorsement policy for the channel. You can then optionally update your channel access control list. - -Note: this topic leverages the instructions on how to update a channel configuration that are found in the [Updating a channel configuration](./config_update.html) tutorial. The environment variables listed here work in conjunction with those commands to update your channels. - -### Edit the peer organizations - -By default, peer organizations are able to make configuration update requests to their own organization on an application channel without needing the approval of any other peer organizations. However, if you are attempting to make a change to a different organization, that organization will have to approve the change. - -You will need to export the following variables: - -* `CH_NAME`: the name of the application channel being updated. -* `ORGNAME`: The name of the organization you are currently updating. -* `TLS_ROOT_CA`: the absolute path to the TLS cert of your ordering node. -* `CORE_PEER_MSPCONFIGPATH`: the absolute path to the MSP representing your organization. -* `CORE_PEER_LOCALMSPID`: the MSP ID of the organization proposing the channel update. This will be the MSP of one of the peer organizations. -* `ORDERER_CONTAINER`: the name of an ordering node container. When targeting the ordering service, you can target any particular node in the ordering service. Your requests will be forwarded to the leader automatically. - -Once you have set the environment variables, navigate to [Step 1: Pull and translate the config](./config_update.html#step-1-pull-and-translate-the-config). - -Then, add the lifecycle organization policy (as listed in `enable_lifecycle.json`) to a file called `modified_config.json` using this command: - -``` -jq -s ".[0] * {\"channel_group\":{\"groups\":{\"Application\": {\"groups\": {\"$ORGNAME\": {\"policies\": .[1].${ORGNAME}Policies}}}}}}" config.json ./enable_lifecycle.json > modified_config.json -``` - -Then, follow the steps at [Step 3: Re-encode and submit the config](./config_update.html#step-3-re-encode-and-submit-the-config). - -### Edit the application channels - -After all of the application channels have been [updated to include V2_0 capabilities](./upgrade_to_newest_version.html#capabilities), endorsement policies for the new chaincode lifecycle must be added to each channel. - -You can set the same environment variables you set when updating the peer organizations. Note that in this case you will not be updating the configuration of an org in the configuration, so the `ORGNAME` variable will not be used. - -Once you have set the environment variables, navigate to [Step 1: Pull and translate the config](./config_update.html#step-1-pull-and-translate-the-config). - -Then, add the lifecycle organization policy (as listed in `enable_lifecycle.json`) to a file called `modified_config.json` using this command: - -``` -jq -s '.[0] * {"channel_group":{"groups":{"Application": {"policies": .[1].appPolicies}}}}' config.json ./enable_lifecycle.json > modified_config.json -``` - -Then, follow the steps at [Step 3: Re-encode and submit the config](./config_update.html#step-3-re-encode-and-submit-the-config). - -For this channel update to be approved, the policy for modifying the `Channel/Application` section of the configuration must be satisfied. By default, this is a `MAJORITY` of the peer organizations on the channel. - -#### Edit channel ACLs (optional) - -The following [Access Control List (ACL)](./access_control.html) in `enable_lifecycle.json` are the default values for the new lifecycle, though you have the option to change them depending on your use case. - -``` -"acls": { - "_lifecycle/CheckCommitReadiness": { - "policy_ref": "/Channel/Application/Writers" - }, - "_lifecycle/CommitChaincodeDefinition": { - "policy_ref": "/Channel/Application/Writers" - }, - "_lifecycle/QueryChaincodeDefinition": { - "policy_ref": "/Channel/Application/Readers" - }, - "_lifecycle/QueryChaincodeDefinitions": { - "policy_ref": "/Channel/Application/Readers" -``` - -You can leave the same environment in place as when you previously edited application channels. - -Once you have the environment variables set, navigate to [Step 1: Pull and translate the config](./config_update.html#step-1-pull-and-translate-the-config). - -Then, add the ACLs (as listed in `enable_lifecycle.json`) and create a file called `modified_config.json` using this command: - -``` -jq -s '.[0] * {"channel_group":{"groups":{"Application": {"values": {"ACLs": {"value": {"acls": .[1].acls}}}}}}}' config.json ./enable_lifecycle.json > modified_config.json -``` - -Then, follow the steps at [Step 3: Re-encode and submit the config](./config_update.html#step-3-re-encode-and-submit-the-config). - -For this channel update to be approved, the policy for modifying the `Channel/Application` section of the configuration must be satisfied. By default, this is a `MAJORITY` of the peer organizations on the channel. - -## Enable new lifecycle in `core.yaml` - -If you follow [the recommended process](./upgrading_your_components.html#overview) for using a tool like `diff` to compare the new version of `core.yaml` packaged with the binaries with your old one, you will not need to add `_lifecycle: enable` to the list of enabled system chaincodes because the new `core.yaml` has added it under `chaincode/system`. - -However, if you are updating your old node YAML file directly, you will have to add `_lifecycle: enable` to the list of enabled system chaincodes. - -For more information about upgrading nodes, check out [Upgrading your components](./upgrading_your_components.html). - - diff --git a/docs/source/updating_capabilities.md b/docs/source/updating_capabilities.md index ff62743509b..3f4205bf713 100644 --- a/docs/source/updating_capabilities.md +++ b/docs/source/updating_capabilities.md @@ -56,7 +56,7 @@ In this example, the ``capabilities.json`` file looks like this (note: if you ar "mod_policy": "Admins", "value": { "capabilities": { - "V2_0": {} + "V3_0": {} } }, "version": "0" @@ -74,7 +74,7 @@ In this example, the ``capabilities.json`` file looks like this (note: if you ar "mod_policy": "Admins", "value": { "capabilities": { - "V2_0": {} + "V2_5": {} } }, "version": "0" @@ -134,7 +134,7 @@ Note that the `mod_policy` for this capability defaults to requiring signatures **As a result, be very careful to not change this capability to a level that does not exist**. Because ordering nodes neither understand nor validate `Application` capabilities, they will approve a configuration to any level and send the new config block to the peers to be committed to their ledgers. However, the peers will be unable to process the capability and will crash. And even it was possible to drive a corrected configuration change to a valid capability level, the previous config block with the faulty capability would still exist on the ledger and cause peers to crash when trying to process it. -This is one reason why a file like `capabilities.json` can be useful. It prevents a simple user error --- for example, setting the `Application` capability to `V20` when the intent was to set it to `V2_0` --- that can cause a channel to be unusable and unrecoverable. +This is one reason why a file like `capabilities.json` can be useful. It prevents a simple user error --- for example, setting the `Application` capability to `V25` when the intent was to set it to `V2_5` --- that can cause a channel to be unusable and unrecoverable. ## Verify a transaction after capabilities have been enabled diff --git a/docs/source/upgrade.rst b/docs/source/upgrade.rst index 8ab687ee241..b5607adcc48 100644 --- a/docs/source/upgrade.rst +++ b/docs/source/upgrade.rst @@ -8,12 +8,10 @@ high level, a four step process. 1. Backup the ledger and MSPs. 2. Upgrade the orderer binaries in a rolling fashion to the latest Fabric version. 3. Upgrade the peer binaries in a rolling fashion to the latest Fabric version. -4. Update the orderer system channel and any application channels to the latest +4. Update application channels to the latest capability levels, where available. Note that some releases will have capabilities in all groups while other releases may have few or even no new capabilities at all. -5. If you want to migrate your network by removing the orderer system channel, - check out :doc:`create_channel/create_channel_participation`. For more information about capabilities, check out :doc:`capabilities_concept`. @@ -21,24 +19,16 @@ For a look at how these upgrade processes are accomplished, please consult these tutorials: 1. :doc:`upgrade_to_newest_version`. This topic discusses the important considerations - for getting to the latest release from the previous release as well as from - the most recent long term support (LTS) release. + for getting to the latest release. 2. :doc:`upgrading_your_components`. Components should be upgraded to the latest version before updating any capabilities. 3. :doc:`updating_capabilities`. Completed after updating the versions of all nodes. -As the upgrading of nodes and increasing the capability levels of channels is by -now considered a standard Fabric process, we will not show the specific commands -for upgrading to the newest release. Similarly, there is no script in the ``fabric-samples`` -repo that will upgrade a sample network from the previous release to this one, -as there has been for previous releases. - -.. note:: It is a best practice to upgrade your SDK to the latest version as a - part of a general upgrade of your network. While the SDK will always - be compatible with equivalent releases of Fabric and higher, it might - be necessary to upgrade to the latest SDK to leverage the latest Fabric - features. Consult the documentation of the Fabric SDK you are using - for information about how to upgrade. +.. note:: SDK applications can be upgraded separate from a general upgrade of your Fabric network. + The `Fabric Gateway client API `_ has been tested with Fabric v2.5 and v3.0. + If you have not yet migrated to the Fabric Gateway client API, + you can `migrate `_ while using a Fabric v2.5 network, + or after you have upgraded to a Fabric v3.0 network. The legacy SDKs are no longer maintained and are not compatible with new v3.0 Fabric features such as SmartBFT consensus. .. toctree:: :maxdepth: 1 diff --git a/docs/source/upgrade_to_newest_version.md b/docs/source/upgrade_to_newest_version.md index e6935027a96..ea6843cea94 100644 --- a/docs/source/upgrade_to_newest_version.md +++ b/docs/source/upgrade_to_newest_version.md @@ -1,135 +1,39 @@ -# Considerations for getting to v2.x +# Considerations for getting to v3.x -In this topic we'll cover recommendations for upgrading from a prior v2.x release to the v2.5 long-term support (LTS) release, as well as from the v1.4 release. +In this topic we'll cover recommendations for upgrading from a v2.x release to a v3.x release. -## Upgrading from a prior v2.x release to the v2.5 LTS release. +## Upgrading from a v2.x release to a v3.x release -Upgrading nodes from a prior v2.x release to the v2.5 LTS release requires no special considerations, simply follow the steps in [Upgrading your components](./upgrading_your_components.html). Upon the first start each v2.5 peer will rebuild some internal indexes for managing private data. +### Before upgrading nodes -The 2.5 release featured one new application capability: +Fabric v3.x has removed some features that were deprecated in v2.x. Before upgrading components to v3.x ensure that you have shifted off of these removed features: -* **Application** capability `V2_5` enables purging the history of private data from a peer while preserving a hash of the private data as immutable evidence on the blockchain as described in the [Purging private data](./private-data/private-data.html#purging-private-data-in-chaincode) concept topic. +- **Support for 'Solo' consensus has been removed in Fabric v3.0.** The 'Solo' consensus type was intended for test environments only in prior releases and has never been supported for production environments. For trial environments you can utilize a single node Raft ordering service as demonstrated in the [test network tutorial](https://hyperledger-fabric.readthedocs.io/en/latest/test_network.html). +- **Support for 'Kafka' consensus has been removed in Fabric v3.0.** If you used Kafka consensus in prior releases, you must migrate to Raft consensus prior to upgrading to v3.x. For details about the migration process, see the [Migrating from Kafka to Raft documentation](https://hyperledger-fabric.readthedocs.io/en/release-2.5/kafka_raft_migration.html). +- **The legacy chaincode lifecycle from v1.x has been removed in Fabric v3.0.** Prior to upgrading peers to v3.x, you must update all channels to utilize the v2.x lifecycle by setting the channel application capability to either V2_0 or V2_5, and redeploying all chaincodes using the v2.x lifecycle. The new chaincode lifecycle provides a more flexible and robust governance model +for chaincodes. For more details see the [documentation for enabling the new lifecycle](https://hyperledger-fabric.readthedocs.io/en/release-2.5/enable_cc_lifecycle.html). -If you would like to take advantage of the new feature, make sure to upgrade your peer binaries before updating the **Application** capability to `V2_5`. If you do not need the new feature, the **Application** capability can remain at `V2_0`. +### Upgrading nodes -For information about how to set new capabilities, check out [Updating the capability level of a channel](./updating_capabilities.html). - -## Upgrading from v1.4.x release to a v2.x release - -Before attempting to upgrade from v1.4.x to v2.x, make sure to consider the following before, during, and after your peer upgrades. - -### Prior to upgrading peer nodes - -It is important to ensure chaincode utilizes good practices consistent with v2.x prior to upgrading nodes and enabling the new chaincode lifecycle. -Consider updating chaincode based on the below guidelines prior to upgrading nodes. - -#### Chaincode shim changes (Go chaincode only) - -The v2.x `ccenv` image that is used to build Go chaincodes no longer automatically vendors the Go chaincode shim dependency like the v1.4 `ccenv` image did. -The recommended approach is to vendor the shim in your v1.4 Go chaincode before making upgrades to the peers and channels, since this approach works with both a v1.4.x and v2.x peer. If you are already using an existing tool such as ``govendor`` you may continue using it to vendor the chaincode shim. Best practice, however, would be to use Go modules to vendor the chaincode shim, as modules are now the de facto standard for dependency management in the Go ecosystem. Note that since Fabric v2.0, chaincode using Go modules without vendored dependencies is also supported. If you do this, you do not need to make any additional changes to your chaincode. - -If you did not vendor the shim in your v1.4 chaincode, the old v1.4 chaincode images will still technically work after peer upgrade, but you are in a risky state. If the chaincode image gets deleted from your environment for whatever reason, the next invoke on v2.x peer will try to rebuild the chaincode image and you'll get an error that the shim cannot be found. - -At this point, you have two options: - -1. If the entire channel is ready to upgrade chaincode, you can upgrade the chaincode on all peers and on the channel (using either the old or new lifecycle depending on the `Application` capability level you have enabled). The best practice at this point would be to vendor the new Go chaincode shim using modules. - -2. If the entire channel is not yet ready to upgrade the chaincode, you can use peer environment variables to specify the v1.4 chaincode environment `ccenv` be used to rebuild the chaincode images. This v1.4 `ccenv` should still work with a v2.x peer. - -To eliminate these concerns, the recommendation is to make sure the chaincode shim is vendored and the chaincode is upgraded, prior to upgrading a peer to v2.x. - -#### Chaincode logger (Go chaincode only) - -Support for user chaincodes to utilize the chaincode shim's logger via `NewLogger()` has been removed. Chaincodes that used the shim's `NewLogger()` must now shift to their own preferred logging mechanism. - -For more information, check out [Logging control](./logging-control.html#chaincode). - -#### Node.js v1.4 Chaincode - -For v1.4 Node.js chaincode libraries, the supported node runtime is v8. Though not formally supported, the v1.4 libraries can work on later versions. For example the Node.js 12 runtime that was used with the Fabric v2.2 `fabric-nodeenv` image. Fabric v2.4 `fabric-nodeenv` has upgraded to Node.js 16 and Fabric v2.5 `fabric-nodeenv` has upgraded to Node.js 18. It is _not possible_ to run the v1.4 libraries on Node.js 16 or Node.js 18. Therefore any chaincode written with the v1.4 libraries will need to be updated prior to upgrading to Fabric v2.4 or Fabric v2.5. - -Also please note that the v1.4 libraries themselves are not supported, and will no longer get updates. Please migrate to a v2.x Node.js chaincode library. - -For detailed information please refer to the [compatibility](https://github.com/hyperledger/fabric-chaincode-node/blob/main/COMPATIBILITY.md) document in the `fabric-chaincode-node` repository. - -#### Chaincode initialization - -The new chaincode lifecycle does not have an option to automatically call a chaincode `Init` function upon chaincode deployment. -Instead, the new chaincode lifecycle has a mechanism to flag that chaincode initialization is required, -by using the `--init-required` flag, and providing a `--isInit` flag on the `peer chaincode invoke` command. -However, in most scenarios it is recommended to embed initialization logic into chaincode rather than use the chaincode lifecycle mechanism. -Chaincode functions often perform checks against existing state, and initialization state can be implemented like any other chaincode state and be checked in subsequent chaincode function calls. -Handling initialization state within chaincode logic rather than with the chaincode lifecycle -mechanism has the benefit that you are not limited to a single initialization function, -rather you are in full control of initialization logic and can call your own -functions that initialize state from an application consistent with how all other application functions are called. - -### While upgrading peer nodes - -#### Peer databases upgrade - -For information about how to upgrade peers, check out our documentation on [upgrading components](./upgrading_your_components.html). During the process for [upgrading your peers](./upgrading_your_components.html#upgrade-the-peers), you will need to perform one additional step to upgrade the peer databases. The databases of all peers (which include not just the state database but the history database and other internal databases for the peer) must be rebuilt using the v2.x data format as part of the upgrade to v2.x. To trigger the rebuild, the databases must be dropped before the peer is started. The instructions below utilize the `peer node upgrade-dbs` command to drop the local databases managed by the peer and prepare them for upgrade, so that they can be rebuilt the first time the v2.x peer starts. If you are using CouchDB as the state database, the peer has support to automatically drop this database as of v2.2. To leverage the support, you must configure the peer with CouchDB as the state database and start CouchDB before running the `upgrade-dbs` command. In v2.0 and v2.1, the peer does not automatically drop the CouchDB state database; therefore you must drop it yourself. - -Follow the commands to upgrade a peer until the `docker run` command to launch the new peer container (you can skip the step where you set an `IMAGE_TAG`, since the `upgrade-dbs` command is for the v2.x release of Fabric only, but you will need to set the `PEER_CONTAINER` and `LEDGERS_BACKUP` environment variables). Instead of the `docker run` command to launch the peer, run this command instead to drop and prepare the local databases managed by the peer (substitute `2.1` for `2.0` in these commands if you are upgrading to that binary version from the 1.4.x LTS): - -``` -docker run --rm -v /opt/backup/$PEER_CONTAINER/:/var/hyperledger/production/ \ - -v /opt/msp/:/etc/hyperledger/fabric/msp/ \ - --env-file ./env.list \ - --name $PEER_CONTAINER \ - hyperledger/fabric-peer:2.0 peer node upgrade-dbs -``` - -In v2.0 and v2.1, if you are using CouchDB as the state database, also drop the CouchDB database. This can be done by removing the CouchDB /data volume directory. - -Then issue this command to start the peer using the `2.0` tag: - -``` -docker run -d -v /opt/backup/$PEER_CONTAINER/:/var/hyperledger/production/ \ - -v /opt/msp/:/etc/hyperledger/fabric/msp/ \ - --env-file ./env.list \ - --name $PEER_CONTAINER \ - hyperledger/fabric-peer:2.0 peer node start -``` - -The peer will rebuild the databases using the v2.x data format the first time it starts. Because rebuilding the databases can be a lengthy process (several hours, depending on the size of your databases), monitor the peer logs to check the status of the rebuild. Every 1000th block you will see a message like `[lockbasedtxmgr] CommitLostBlock -> INFO 041 Recommitting block [1000] to state database` indicating the rebuild is ongoing. - -If the database is not dropped as part of the upgrade process, the peer start will return an error message stating that its databases are in the old format and must be dropped using the `peer node upgrade-dbs` command above (or dropped manually if using CouchDB state database). The node will then need to be restarted again. +Upgrading nodes from a v2.x release to a v3.x release requires no special considerations, simply follow the steps in [Upgrading your components](./upgrading_your_components.html). ### After upgrading nodes -#### Chaincode lifecycle - -The new chaincode lifecycle that debuted in v2.0 allows multiple organizations to agree on how a chaincode will be operated before it can be used on a channel. For more information about the new chaincode lifecycle, check out [Fabric chaincode lifecycle](./chaincode_lifecycle.html) concept topic. - -It is a best practice to upgrade all of the peers on a channel before enabling the `Channel` and `Application` capabilities that enable the new chaincode lifecycle (the `Channel` capability is not strictly required, but it makes sense to update it at this time). Note that any peers that are not at v2.x will crash after enabling either capability, while any ordering nodes that are not at v2.x will crash after the `Channel` capability has been enabled. This crashing behavior is intentional, as the peer or orderer cannot safely participate in the channel if it does not support the required capabilities. - -After the `Application` capability has been updated to `V2_0` on a channel, chaincodes that were deployed using the v1.x chaincode lifecycle will continue to run, and will continue to utilize the same chaincode endorsement policy as before. -However, the next time that you would like to update these chaincodes, you must utilize the v2.x lifecycle procedures to package, install, approve, and commit chaincodes on the channel. This will effectively shift the chaincode from the v1.x lifecycle framework to the v2.x lifecycle framework. -Additionally, any new chaincode deployments must also utilize the v2.x lifecycle procedures to package, install, approve, and commit chaincodes on the channel. -As a result, make sure to be prepared for the new lifecycle before updating the capability. - -The new lifecycle defaults to using the endorsement policy configured in the channel config (e.g., a `MAJORITY` of orgs). Therefore this endorsement policy should be added to the channel configuration when enabling capabilities on the channel. - -For information about how to edit the relevant channel configurations to enable the new lifecycle by adding an endorsement policy for each organization, check out [Enabling the new chaincode lifecycle](./enable_cc_lifecycle.html). - #### Capabilities -The 2.0 release featured three new capabilities. +The 3.0 release features one new capability. -* **Application** `V2_0`: enables the new chaincode lifecycle as described in [Fabric chaincode lifecycle](./chaincode_lifecycle.html) concept topic. +* **Channel** `V3_0`: this channel capability enables SmartBFT consensus and adds support for Ed25519 cryptographic algorithm in MSP credentials. Both features impact orderer node and peer node behavior. -* **Channel** `V2_0`: this capability has no changes, but is used for consistency with the application and orderer capability levels. - -* **Orderer** `V2_0`: controls `UseChannelCreationPolicyAsAdmins`, changing the way that channel creation transactions are validated. When combined with the `-baseProfile` option of configtxgen, values which were previously inherited from the orderer system channel may now be overridden. - -As with any update of the capability levels, make sure to upgrade your peer binaries before updating the `Application` and `Channel` capabilities, and make sure to upgrade your orderer binaries before updating the `Orderer` and `Channel` capabilities. +Make sure to upgrade all orderer binaries and peer binaries before updating the `Channel` capability. Additionally, ensure that `OrdererEndpoints` are set at the organization level before updating to the V3_0 channel capability. See the next section **Define ordering node endpoint per org**. For information about how to set new capabilities, check out [Updating the capability level of a channel](./updating_capabilities.html). -#### Define ordering node endpoint per org (recommend) +#### Define ordering node endpoint per org + +Starting with version v1.4.2, it was recommended to define orderer endpoints in all channels at the organization level by adding a new `OrdererEndpoints` stanza within the channel configuration of an organization, replacing the global `OrdererAddresses` section of channel configuration. This update is required prior to enabling the V3_0 channel capability. -Starting with version v1.4.2, it was recommended to define orderer endpoints in all channels at the organization level by adding a new `OrdererEndpoints` stanza within the channel configuration of an organization, replacing the global `OrdererAddresses` section of channel configuration. If at least one organization has an ordering service endpoint defined at an organizational level, all orderers and peers will ignore the channel level endpoints when connecting to ordering nodes. +If at least one organization has an ordering service endpoint defined at an organizational level, all orderers and peers will ignore the channel level endpoints when connecting to ordering nodes. Utilizing organization level orderer endpoints is required when using service discovery with ordering nodes provided by multiple organizations. This allows clients to provide the correct organization TLS certificates. @@ -173,5 +77,9 @@ Then, follow the steps at [Step 3: Re-encode and submit the config](./config_upd If every ordering service organization performs their own channel edit, they can edit the configuration without needing further signatures (by default, the only signature needed to edit parameters within an organization is an admin of that organization). If a different organization proposes the update, then the organization being edited will need to sign the channel update request. +#### Migrate to SmartBFT consensus (optional) + +You may continue utilizing Raft consensus for a Crash Fault Tolerant ordering service, or [migrate to SmartBFT consensus](./raft_bft_migration.html) for a Byzantine Fault Tolerant ordering service after updating to the `V3_0` channel capability. SmartBFT may make sense if you distribute ordering service nodes across multiple organizations, but note that throughput may go down due to the additional consensus requirements. + diff --git a/docs/source/upgrading_your_components.md b/docs/source/upgrading_your_components.md index 719124d2f2d..46b371318c3 100644 --- a/docs/source/upgrading_your_components.md +++ b/docs/source/upgrading_your_components.md @@ -25,6 +25,8 @@ To do this, backup the `orderer.yaml` or `core.yaml` file (for the peer) and rep This tutorial assumes a Docker deployment where the YAML files will be baked into the images and environment variables will be used to overwrite the defaults in the configuration files. +See the release notes for details about any important changes in the configuration files. + ## Environment variables for the binaries When you deploy a peer or an ordering node, you had to set a number of environment variables relevant to its configuration. A best practice is to create a file for these environment variables, give it a name relevant to the node being deployed, and save it somewhere on your local file system. That way you can be sure that when upgrading the peer or ordering node you are using the same variables you set when creating it. @@ -97,7 +99,7 @@ Export the following environment variables before attempting to upgrade your ord * `ORDERER_CONTAINER`: the name of your ordering node container. Note that you will need to export this variable for each node when upgrading it. * `LEDGERS_BACKUP`: the place in your local filesystem where you want to store the ledger being backed up. As you will see below, each node being backed up will have its own subfolder containing its ledger. You will need to create this folder. -* `IMAGE_TAG`: the Fabric version you are upgrading to. For example, `2.0`. +* `IMAGE_TAG`: the Fabric version you are upgrading to. For example, `3.0`. Note that you will have to set an **image tag** to ensure that the node you are starting using the correct images. The process you use to set the tag will depend on your deployment method. @@ -149,7 +151,7 @@ Export the following environment variables before attempting to upgrade your pee * `PEER_CONTAINER`: the name of your peer container. Note that you will need to set this variable for each node. * `LEDGERS_BACKUP`: the place in your local filesystem where you want to store the ledger being backed up. As you will see below, each node being backed up will have its own subfolder containing its ledger. You will need to create this folder. -* `IMAGE_TAG`: the Fabric version you are upgrading to. For example, `2.0`. +* `IMAGE_TAG`: the Fabric version you are upgrading to. For example, `3.0`. Note that you will have to set an **image tag** to ensure that the node you are starting is using the correct images. The process you use to set the tag will depend on your deployment method. @@ -213,7 +215,7 @@ To learn how to upgrade your Fabric CA server, click over to the [CA documentati ## Upgrade SDK clients -Upgrade Fabric before upgrading SDK clients. Fabric is tested for backwards compatibility with older SDK clients. While newer SDK clients often work with older Fabric releases, they may expose features that are not yet available in the older Fabric releases, and are not tested for full compatibility. +SDK applications can be upgraded separate from a general upgrade of your Fabric network. The `Fabric Gateway client API `_ has been tested with Fabric v2.5 and v3.0. If you have not yet migrated to the Fabric Gateway client API, you can `migrate `_ while using a Fabric v2.5 network, or after you have upgraded to a Fabric v3.0 network. The legacy SDKs are no longer maintained and are not compatible with new v3.0 Fabric features such as SmartBFT consensus. ## Upgrading CouchDB @@ -226,21 +228,9 @@ To upgrade CouchDB: 3. Install the latest CouchDB binaries or update deployment scripts to use a new Docker image. 4. Restart CouchDB. -## Upgrade Node chaincode shim - -To move to the new version of the Node chaincode shim a developer would need to: - -1. Change the level of `fabric-shim` in their chaincode `package.json` from their old level to the new one. -2. Repackage this new chaincode package and install it on all the endorsing peers in the channel. -3. Perform an upgrade to this new chaincode. To see how to do this, check out [Peer chaincode commands](./commands/peerchaincode.html). - -## Upgrade Chaincodes with vendored shim - -For information about upgrading the Go chaincode shim specific to the v2.0 release, check out [Chaincode shim changes](./upgrade_to_newest_version.html#chaincode-shim-changes). - -A number of third party tools exist that will allow you to vendor a chaincode shim. If you used one of these tools, use the same one to update your vendored chaincode shim and re-package your chaincode. +## Upgrading chaincodes -If your chaincode vendors the shim, after updating the shim version, you must install it to all peers which already have the chaincode. Install it with the same name, but a newer version. Then you should execute a chaincode upgrade on each channel where this chaincode has been deployed to move to the new version. +You generally do not need to update chaincodes when updating the Fabric node versions.