[ja_JP] Upgrading to the latest release / Considerations for getting to v2.x
Opened this issue · 0 comments
shimos commented
Original HTML: https://hyperledger-fabric.readthedocs.io/en/release-2.5/upgrade_to_newest_version.html
Original Source: https://github.com/hyperledger/fabric/blob/e1e8e2e52aa4fc543360d245fe6554a0eaf81183/docs/source/upgrade_to_newest_version.md
diff --git a/docs/source/upgrade_to_newest_version.md b/docs/source/upgrade_to_newest_version.md
index e6651fd4b..412b8c60e 100644
--- a/docs/source/upgrade_to_newest_version.md
+++ b/docs/source/upgrade_to_newest_version.md
@@ -1,33 +1,34 @@
# Considerations for getting to v2.x
-In this topic we'll cover recommendations for upgrading to the newest release from the previous release as well as from the most recent long term support (LTS) release.
+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.
-## Upgrading from 2.1 to 2.2
+## Upgrading from a prior v2.x release to the v2.5 LTS release.
-The 2.1 and 2.2 releases of Fabric are stabilization releases, featuring bug fixes and other forms of code hardening. As such there are no particular considerations needed for upgrade, and no new capability levels requiring particular image versions or channel configuration updates.
+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.
-## Upgrading to 2.2 from the 1.4.x long term support release
+The 2.5 release featured one new application capability:
-Before attempting to upgrade from v1.4.x to v2.2, make sure to consider the following:
+* **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.
-### Chaincode lifecycle
+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`.
-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.
+For information about how to set new capabilities, check out [Updating the capability level of a channel](./updating_capabilities.html).
-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.
+## Upgrading from v1.4.x release to a v2.x release
-After the `Application` capability has been updated to `V2_0` on a channel, you must use the v2.x lifecycle procedures to package, install, approve, and commit new chaincodes on the channel. As a result, make sure to be prepared for the new lifecycle before updating the capability.
+Before attempting to upgrade from v1.4.x to v2.x, make sure to consider the following before, during, and after your peer upgrades.
-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.
+### Prior to upgrading peer nodes
-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).
+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)
+#### 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 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 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.
+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:
@@ -35,13 +36,37 @@ At this point, you have two options:
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.
-### Chaincode logger (Go chaincode only)
+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).
-### Peer databases upgrade
+#### 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.
@@ -71,7 +96,24 @@ The peer will rebuild the databases using the v2.x data format the first time it
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.
-### Capabilities
+### 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 deployements 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.
@@ -85,9 +127,9 @@ As with any update of the capability levels, make sure to upgrade your peer bina
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 (recommend)
-Starting with version v1.4.2, it was recommended to define orderer endpoints in both the system channel and in all application 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.
+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.
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.
@@ -112,10 +154,10 @@ In this example, we will create a stanza for a single org called `OrdererOrg`. N
Then, export the following environment variables:
-* `CH_NAME`: the name of the channel being updated. Note that all system channels and application channels should contain organization endpoints for ordering nodes.
+* `CH_NAME`: the name of the channel being updated.
* `CORE_PEER_LOCALMSPID`: the MSP ID of the organization proposing the channel update. This will be the MSP of one of the orderer organizations.
* `CORE_PEER_MSPCONFIGPATH`: the absolute path to the MSP representing your organization.
-* `TLS_ROOT_CA`: the absolute path to the root CA certificate of the organization proposing the system channel update.
+* `TLS_ROOT_CA`: the absolute path to the root CA certificate of the organization proposing the channel update.
* `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.
* `ORGNAME`: The name of the organization you are currently updating. For example, `OrdererOrg`.