# Considerations for getting to v2.x

このトピックでは、以前のリリースあるいは最新の長期サポート(LTS)リリースから最新のリリースへアップグレードするときの推奨項目について扱います。

## Upgrading from 2.1 to 2.2

Fabricの2.1と2.2リリースは安定化リリースであり、バグ修正やコードの堅牢化を特徴としています。
そのため、アップグレードに関して特別な注意事項や、特定のイメージバージョンやチャネルのコンフィギュレーションのアップデートを必要とするような新しいケーパビリティレベルはありません。

## Upgrading to 2.2 from the 1.4.x long term support release

v1.4.xからv2.2へアップグレードしようとする前に、以下の項目を考慮するようにしてください。

### Chaincode lifecycle

v2.0で登場した新しいチェーンコードライフサイクルによって、複数の組織がチェーンコードがチャネルで利用可能になる前に、どのように運用されるかについて合意することができます。
新しいチェーンコードライフサイクルについてより詳しくは、 [Fabricチェーンコードライフサイクル](./chaincode_lifecycle.html) の概念のトピックを参照してください。

新しいチェーンコードライフサイクルを有効化する `Channel` と `Application` ケーパビリティを有効にする前に、チャネルのすべてのピアをアップグレードするのが、良いやり方です (`Channel` ケーパビリティについては厳密には必須ではありませんが、このときにアップデートするのが合理的です)。
いずれかのケーパビリティを有効にすると、v2.xになってないピアはクラッシュするでしょう。
また、 `Channel` ケーパビリティを有効にすると、v2.xになっていないオーダリングノードはクラッシュするでしょう。
このクラッシュするという挙動は意図的なもので、必要なケーパビリティをサポートしていないピアやordererは、安全にチャネルに加わることができないためです。

チャネルの `Application` ケーパビリティを `V2_0` にアップデートした後は、そのチャネルへの新しいチェーンコードのパッケージ化、インストール、承認、コミットというv2.xのライフサイクルの手順を使う必要があります。
ですので、ケーパビリティをアップデートする前に、新しいライフサイクルへの準備が整っていることを確認してください。

新しいライフサイクルでは、チャネル設定で設定されたエンドースメントポリシー(たとえば、組織の `MAJORITY` (過半数))をデフォルトで使うようになっています。
そのため、チャネルでケーパビリティを有効にするときには、エンドースメントポリシーをチャネル設定に加えなければなりません。

関係するチャネル設定を編集して、各組織でエンドースメントポリシーを加えて新しいライフサイクルを有効する方法については、 [新しいチェーンコードライフサイクルの有効化](./enable_cc_lifecycle.html) を参照してください。

### Chaincode shim changes (Go chaincode only)

Goチェーンコードをビルドするときに使われるv2.xの `ccenv` イメージでは、v1.4の `ccenv` イメージとは異なり、Goチェーンコードの shim 依存関係をベンダリングは自動的には行いません。
推奨するアプローチは、ピアとチャネルのアップグレードを行う前に、v1.4のGoチェーンコードでshimをベンダリングしておくことです。
このアプローチはv1.4.xとv2.xのピアの両方で動くからです。
もし、既に ``goverdor`` のような既存のツールを使っている場合には、チェーンコードのshimのベンダリングに使い続けてもいいでしょう。
しかし、ベストプラクティスは、チェーンコードのshimのベンダリングにGoモジュールを使うことです。
これは、モジュールが、Goのエコシステムにおいて依存関係管理の事実上の標準となっているからです。
Fabric v2.0以降では、ベンダリングされた依存関係を含まない、Goモジュールを利用したチェーンコードもサポートされています。
モジュールを使う場合には、チェーンコードに新たな変更を行う必要はありません。

v1.4のチェーンコードに対してshimをベンダリングしなかった場合、技術的にはアップグレード後も古いv1.4のチェーンコードイメージは動き続けます。
しかし、これは危険な状態です。
もし、チェーンコードのイメージが何らかの理由で環境から削除されたとすると、v2.xピアでの次の実行においては、チェーンコードのイメージをリビルドが行われようとし、shimが見つからないというエラーが返ってきてしまうでしょう。

こうなった場合には、2つの選択肢があります。

1. チャネル全体がチェーンコードをアップグレードできる状態であれば、全てのピアとチャネルでチェーンコードをアップグレードすることができます。(有効になっている `Application` ケーパビリティレベルによって新旧どちらかのライフサイクルを使う)
   このときのベストプラクティスは、新しいGoチェーンコードのshimをモジュールを使ってベンダリングすることでしょう。

2. チャネル全体がまだチェーンコードをアップグレードできる状態でない場合は、ピアの環境変数を使って、チェーンコードイメージのリビルドで、v1.4のチェーンコード環境 `ccenv` が使われるように指定することができます。
   このv1.4の `ccenv` はv2.xのピアとも正しく動作します。

### Chaincode logger (Go chaincode only)

`NewLogger()` を用いた、ユーザーのチェーンコードからのチェーンコードshimのロガー利用のサポートは削除されました。
shimの `NewLogger()` を使っていたチェーンコードは、自分で用意したログ機構に移行しなければなりません。

より詳細については、[ログの制御](./logging-control.html#chaincode) を参照してください。

### Peer databases upgrade

ピアのアップグレードについては、[コンポーネントのアップグレード](./upgrading_your_components.html) のドキュメントを参照してください。
[ピアのアップグレード](./upgrading_your_components.html#upgrade-the-peers) のプロセスでは、ピアのデータベースのアップグレードのために一つ追加の手順を行う必要があります。
全てのピアのデータベース(ステートデータベースだけでなく、履歴のデータベースやピアのそのほかの内部データベースを含む)は、v2.xのアップグレードの一部として、v2.xのデータフォーマットを用いて再構築する必要があります。
この再構築を実行するために、ピアの開始前にデータベースを削除する必要があります。
下記の手順では、 `peer node upgrade-dbs` コマンドを使って、v2.xのピアの初回起動時に再構築されるように、ピアに管理されているデータベースを削除しアップグレードに備えます。
もしCouchDBをステートデータベースとして使っている場合には、v2.2時点でピアがこのデータベースの自動的な削除をサポートしています。
このサポートを利用するためには、CouchDBをステートデータベースとするようにピアを設定し、 `upgrade-dbs` コマンドを実行する前にCouchDBを起動する必要があります。
v2.0とv2.1では、ピアはCouchDBのステートデータベースを自動的には削除しないため、自分で削除する必要があります。

ピアをアップグレードするところから、 `docker run` コマンドで新しいピアコンテナを起動する直前までのコマンドに従ってください。(`upgrade-dbs` コマンドはFabricのv2.xリリースのみなので、 `IMAGE_TAG` をセットする手順は飛ばすことができます。ただし、 `PEER_CONTAINER` と `LEDGERS_BACKUP` 環境変数を設定する必要があるでしょう)
`docker run` コマンドでピアを起動する代わりに、ピアが管理しているローカルデータベースを削除し準備するために次のコマンドを実行してください。 (もし1.4.x LTSから2.1にアップグレードする場合には、コマンドの `2.0` を `2.1` で置き換えてください。)

```
docker run --rm -v /opt/backup/$PEER_CONTAINER/:/var/hyperledger/production/ \
            -v /opt/msp/:/etc/hyperledger/fabric/msp/ \
            --env-file ./env<name of node>.list \
            --name $PEER_CONTAINER \
            hyperledger/fabric-peer:2.0 peer node upgrade-dbs
```

v2.0とv2.1で、CouchDBをステートデータベースとして使っている場合には、CouchDBデータベースも削除してください。
これは、CouchDBの/dataボリュームディレクトリを削除することでできます。

次に、下記のコマンドを実行して、 `2.0` タグでピアを起動してください。

```
docker run -d -v /opt/backup/$PEER_CONTAINER/:/var/hyperledger/production/ \
            -v /opt/msp/:/etc/hyperledger/fabric/msp/ \
            --env-file ./env<name of node>.list \
            --name $PEER_CONTAINER \
            hyperledger/fabric-peer:2.0 peer node start
```

ピアは、初回起動時にv2.xデータフォーマットを使ってデータベースを再構築します。
データベースの再構築は、非常に時間がかかることがあるプロセス (データベースのサイズにより数時間)なので、ピアのログを見て再構築のステータスをチェックしてください。
1000ブロックごとに、再構築が進行中であることを示す `[lockbasedtxmgr] CommitLostBlock -> INFO 041 Recommitting block [1000] to state database` のようなメッセージが見えるでしょう。

アップグレードプロセスの中でデータベースを削除しなかった場合、ピアは、データベースが古いフォーマットであり上記の `peer node upgrade-dbs` を使って削除(CouchDBステートデータベースを使っている場合には、手動で削除)する必要があるというエラーメッセージを返すでしょう。
その後、ノードはまた再度開始する必要があります。

### Capabilities

2.0リリースには、3つの新しいケーパビリティがあります。

* **Application** `V2_0`: [Fabricチェーンコードライフサイクル](./chaincode_lifecycle.html) の概念のトピックで述べられている新しいチェーンコードライフサイクルを有効にします。

* **Channel** `V2_0`: このケーパビリティは特に変更はありませんが、アプリケーションとordererのケーパビリティと一貫性を保つために使われます。

* **Orderer** `V2_0`: `UseChannelCreationPolicyAsAdmins` を制御し、チャネル作成トランザクションの検証方法を変更します。
  configtxgenの `-baseProfile` オプションと組み合わせることで、以前はordererシステムチャネルから引き継がれていた値を上書きすることができます。

ケーパビリティレベルをアップデートする際には、 `Application` と `Channel` ケーパビリティをアップデートする前には、ピアのバイナリをアップグレードしていることを、 `Orderer` と `Channel` ケーパビリティをアップデートする前には、ordererのバイナリをアップグレードしていることを確かめてください。

新しいケーパビリティについては、[チャネルのケーパビリティレベルのアップデート](./updating_capabilities.html) を参照してください。

### Define ordering node endpoint per org (recommend)

v1.4.2以降では、システムチャネルとアプリケーションチャネルの組織レベルの両方でordererのエンドポイントを定義することが推奨されます。
これは、チャネル設定内のグローバルの `OrdererAddresses` セクションの代わりに、新しい `OrdererEndpoints` の項目を追加することで行います。
もし組織の一つでもオーダリングサービスのエンドポイントを組織レベルで定義している場合、全てのordererとピアはオーダリングノードに接続する際にチャネルレベルのエンドポイントを無視します。

複数組織によるオーダリングノードをサービスディスカバリで利用するときに、組織レベルのordererのエンドポイントは必須となります。
これによってクライアントが正しく組織のTLS証明書を指定することができるようになります。

もし、チャネル設定に組織ごとの `OrdererEndpoints` がまだない場合には、チャネル設定のアップデートを実行して、チャネル設定に追加する必要があります。
最初に、新しい設定項目を含むJSONファイルを作成してください。

この例では、 `OrdererOrg` という一組織のための項目を作成します。
もし複数のオーダリングサービス組織がある場合には、全てエンドポイントを含むようにアップデートする必要があります。
このJSONファイルを `orglevelEndpoints.json` と名前を付けましょう。

```
{
  "OrdererOrgEndpoint": {
      "Endpoints": {
          "mod_policy": "Admins",
          "value": {
              "addresses": [
                 "127.0.0.1:30000"
              ]
          }
      }
   }
}
```

そして、下記の環境変数をエクスポートしてください。

* `CH_NAME`: アップデートするチャネルの名前。全てのシステムチャネルとアプリケーションチャネルがオーダリングノードの組織ごとのエンドポイントを持つ必要があります。
* `CORE_PEER_LOCALMSPID`: チャネルアップデートを提案する組織のMSP ID。これは、orderer組織のいずれかのMSPになるでしょう。
* `CORE_PEER_MSPCONFIGPATH`: 組織のMSPへの絶対パス。
* `TLS_ROOT_CA`: システムチャネルアップデートを提案する組織のルートCA証明書への絶対パス。
* `ORDERER_CONTAINER`: オーダリングノードコンテナの名前。オーダリングサービスを対象とする際には、そのうちのどのノードでも対象にすることができます。リクエストは台帳に自動的に転送されます。
* `ORGNAME`: アップデートする組織の名前。例えば、 `OrdererOrg`

環境変数を設定したら、 [ステップ1: 設定の取得と変換](./config_update.html#step-1-pull-and-translate-the-config) に進んでください。

そして、次のコマンドによって、ライフサイクルの組織ポリシー(`orglevelEndpoints.json` 内に記述)を `modified_config.json` に追加してください。

```
jq -s ".[0] * {\"channel_group\":{\"groups\":{\"Orderer\": {\"groups\": {\"$ORGNAME\": {\"values\": .[1].${ORGNAME}Endpoint}}}}}}" config.json ./orglevelEndpoints.json > modified_config.json
```

その後、 [ステップ3: 再エンコードと設定の送信](./config_update.html#step-3-re-encode-and-submit-the-config) の手順に従ってください。

各オーダリングサービス組織が自分のチャネルの編集を行う場合、他の署名を必要とせずに設定を編集することができます。(デフォルトでは、組織内のパラメータを編集するのに必要な署名は、その組織の管理者のみです)
もし、別の組織がアップデートを提案する場合には、編集される組織がチャネルアップデートリクエストに署名する必要があります。

<!--- Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/ -->