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チェーンコードライフサイクルの概念のトピックを参照してください。

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

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

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

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

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つの選択肢があります。

チャネル全体がチェーンコードをアップグレードできる状態であれば、全てのピアとチャネルでチェーンコードをアップグレードすることができます。(有効になっている Application ケーパビリティレベルによって新旧どちらかのライフサイクルを使う) このときのベストプラクティスは、新しいGoチェーンコードのshimをモジュールを使ってベンダリングすることでしょう。
チャネル全体がまだチェーンコードをアップグレードできる状態でない場合は、ピアの環境変数を使って、チェーンコードイメージのリビルドで、v1.4のチェーンコード環境 ccenv が使われるように指定することができます。このv1.4の ccenv はv2.xのピアとも正しく動作します。

Chaincode logger (Go chaincode only)¶

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

より詳細については、ログの制御を参照してください。

Peer databases upgrade¶

ピアのアップグレードについては、コンポーネントのアップグレードのドキュメントを参照してください。ピアのアップグレードのプロセスでは、ピアのデータベースのアップグレードのために一つ追加の手順を行う必要があります。全てのピアのデータベース(ステートデータベースだけでなく、履歴のデータベースやピアのそのほかの内部データベースを含む)は、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チェーンコードライフサイクルの概念のトピックで述べられている新しいチェーンコードライフサイクルを有効にします。
Channel V2_0: このケーパビリティは特に変更はありませんが、アプリケーションとordererのケーパビリティと一貫性を保つために使われます。
Orderer V2_0: UseChannelCreationPolicyAsAdmins を制御し、チャネル作成トランザクションの検証方法を変更します。 configtxgenの -baseProfile オプションと組み合わせることで、以前はordererシステムチャネルから引き継がれていた値を上書きすることができます。

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

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

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: 設定の取得と変換に進んでください。

そして、次のコマンドによって、ライフサイクルの組織ポリシー(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: 再エンコードと設定の送信の手順に従ってください。

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