etcdを3.3から3.4にアップグレード
通常、etcd 3.3から3.4へのアップグレードは、停止時間なしのローリングアップグレードで実行できます。
- etcd v3.3のプロセスを1つずつ停止し、etcd v3.4のプロセスに置き換えます。
- すべてのプロセスがv3.4で稼働すると、クラスターでv3.4の新機能を利用できます。
アップグレードを開始する 前に、このガイドの残りを読んで準備してください。
アップグレードのチェックリスト
v3データのないv2から移行する
場合、v3のETCD_DATA_DIR/member/snap/dbファイルがない状態で既存のスナップショットからリストアすると、etcdサーバーv3.2+でパニックが発生します。これは、以前のv3データがないままサーバーをv2から移行した場合に起こります。この動作は、v3データの意図しない消失(たとえばdbファイルが移動された場合)を防ぐ役割も果たします。etcdでは、v3への移行後はv3データが存在する場合にのみ、さらに移行を進められます。v3.0サーバーにv3データが存在するまでは、それより新しいv3バージョンにアップグレードしないでください。
3.4の主な互換性を損なう変更は次のとおりです。
ETCDCTL_API=3 etcdctlをデフォルトに変更
ETCDCTL_API=3がデフォルトになりました。
etcd --enable-v2=falseをデフォルトに変更
etcd --enable-v2=false
がデフォルトになりました。
つまり、etcd --enable-v2=trueを指定しない限り、etcd v3.4サーバーはv2 APIリクエストを処理しません。
v2 APIを使用していた場合は、v3.4で必ずv2 APIを有効にしてください。
その他のHTTP APIは引き続き動作します(例:[CLIENT-URL]/metrics、[CLIENT-URL]/health、v3 gRPCゲートウェイ)。
etcd --ca-fileおよびetcd --peer-ca-fileフラグの非推奨化
--ca-fileおよび--peer-ca-fileフラグは非推奨です。これらはv2.1から非推奨となっています。
このパラメーターを設定すると、--client-cert-authの値にかかわらず、クライアント証明書認証も自動的に有効になることに注意してください。
grpc.ErrClientConnClosingエラーの非推奨化
grpc.ErrClientConnClosingはgRPC >= 1.10で非推奨になりました
。
クライアントの接続にgrpc.WithBlockが必要
新しいクライアントバランサー
は、非同期リゾルバーを使用してgRPCの接続関数にエンドポイントを渡します。そのため、v3.4クライアントでは、基盤となる接続の確立を待つために、接続オプションgrpc.WithBlockが必要です。
Prometheusメトリクスetcd_debugging_mvcc_db_total_size_in_bytesの非推奨化
v3.4では、etcdストレージの監視を促すため、Prometheusメトリクスetcd_debugging_mvcc_db_total_size_in_bytesをetcd_mvcc_db_total_size_in_bytesに昇格させています。
後方互換性のため、v3.4ではetcd_debugging_mvcc_db_total_size_in_bytesも引き続き提供されます。v3.5で完全に非推奨になります。
etcd_debugging_*名前空間のメトリクスは、実験的機能と位置付けられていることに注意してください。監視ガイドの改善に伴い、さらに多くのメトリクスを昇格させる可能性があります。
Prometheusメトリクスetcd_debugging_mvcc_put_totalの非推奨化
v3.4では、etcdストレージの監視を促すため、Prometheusメトリクスetcd_debugging_mvcc_put_totalをetcd_mvcc_put_totalに昇格させています。
後方互換性のため、v3.4ではetcd_debugging_mvcc_put_totalも引き続き提供されます。v3.5で完全に非推奨になります。
etcd_debugging_*名前空間のメトリクスは、実験的機能と位置付けられていることに注意してください。監視ガイドの改善に伴い、さらに多くのメトリクスを昇格させる可能性があります。
Prometheusメトリクスetcd_debugging_mvcc_delete_totalの非推奨化
v3.4では、etcdストレージの監視を促すため、Prometheusメトリクスetcd_debugging_mvcc_delete_totalをetcd_mvcc_delete_totalに昇格させています。
後方互換性のため、v3.4ではetcd_debugging_mvcc_delete_totalも引き続き提供されます。v3.5で完全に非推奨になります。
etcd_debugging_*名前空間のメトリクスは、実験的機能と位置付けられていることに注意してください。監視ガイドの改善に伴い、さらに多くのメトリクスを昇格させる可能性があります。
Prometheusメトリクスetcd_debugging_mvcc_txn_totalの非推奨化
v3.4では、etcdストレージの監視を促すため、Prometheusメトリクスetcd_debugging_mvcc_txn_totalをetcd_mvcc_txn_totalに昇格させています。
後方互換性のため、v3.4ではetcd_debugging_mvcc_txn_totalも引き続き提供されます。v3.5で完全に非推奨になります。
etcd_debugging_*名前空間のメトリクスは、実験的機能と位置付けられていることに注意してください。監視ガイドの改善に伴い、さらに多くのメトリクスを昇格させる可能性があります。
Prometheusメトリクスetcd_debugging_mvcc_range_totalの非推奨化
v3.4では、etcdストレージの監視を促すため、Prometheusメトリクスetcd_debugging_mvcc_range_totalをetcd_mvcc_range_totalに昇格させています。
後方互換性のため、v3.4ではetcd_debugging_mvcc_range_totalも引き続き提供されます。v3.5で完全に非推奨になります。
etcd_debugging_*名前空間のメトリクスは、実験的機能と位置付けられていることに注意してください。監視ガイドの改善に伴い、さらに多くのメトリクスを昇格させる可能性があります。
etcd --log-outputフラグの非推奨化(現在は--log-outputs)
複数のログ出力をサポートするため、etcd --log-outputを--log-outputsに改名しました
。etcd --logger=capnslogは複数のログ出力をサポートしません。
etcd --log-outputはv3.5で非推奨になります。etcd --logger=capnslogはv3.5で非推奨になります。
v3.4では、構造化ログと複数のログ出力に対応するため、etcd --logger=zap --log-outputs=stderrのサポートを追加しています。主な狙いは、障害が発生してからサーバーログを調べるのではなく、etcdの監視を自動化することです。今後の開発ではetcdのログ出力をできるだけ少なくし、メトリクスとアラートでetcdを監視しやすくします。etcd --logger=capnslogはv3.5で非推奨になります。
etcd --config-fileのlog-outputsフィールドの型を[]stringに変更
log-outputs(以前のフィールド名はlog-output)が複数のライターを受け付けるようになったため、etcdの設定YAMLファイルのlog-outputsフィールドは、次のように[]string型に変更しなければなりません。
embed.Config.LogOutputをembed.Config.LogOutputsに改名
複数のログ出力をサポートするため、**embed.Config.LogOutputをembed.Config.LogOutputs**に改名しました
。また、複数のログ出力をサポートするため、embed.Config.LogOutputの型をstringから[]stringに変更しました
。
v3.5でcapnslogを非推奨化
v3.5では、capnslog用のetcd --log-package-levelsフラグが非推奨になります。etcd --logger=zap --log-outputs=stderrがデフォルトになります。v3.5では、[CLIENT-URL]/config/local/logエンドポイントが非推奨になります。
etcd --debugフラグの非推奨化(現在は--log-level=debug)
v3.4では、etcd --debug
フラグが非推奨になります。代わりにetcd --log-level=debugフラグを使用してください。
pkg/transport.TLSInfo.CAFileフィールドの非推奨化
pkg/transport.TLSInfo.CAFileフィールドは非推奨になりました。
embed.Config.SnapCountをembed.Config.SnapshotCountに変更
フラグ名etcd --snapshot-countと一貫性を持たせるため、embed.Config.SnapCountフィールドはembed.Config.SnapshotCountに改名されました。
etcdserver.ServerConfig.SnapCountをetcdserver.ServerConfig.SnapshotCountに変更
フラグ名etcd --snapshot-countと一貫性を持たせるため、etcdserver.ServerConfig.SnapCountフィールドはetcdserver.ServerConfig.SnapshotCountに改名されました。
walパッケージの関数シグネチャの変更
構造化ロガーをサポートするため、walの関数シグネチャを変更しました。
pkg/adtパッケージのIntervalTree型の変更
pkg/adt.IntervalTreeはinterfaceとして定義されるようになりました。
embed.Config.SetupLoggingの非推奨化
誤ったログ設定を防ぐため、embed.Config.SetupLoggingは削除され、ログ設定は自動的に行われるようになりました。
gRPCゲートウェイのHTTPエンドポイントの変更(/v3betaを/v3に置き換え)
変更前
変更後
/v3betaエンドポイントへのリクエストは/v3にリダイレクトされ、/v3betaは3.5リリースで削除されます。
コンテナーイメージタグの非推奨化
latestおよびマイナーバージョンのイメージタグは非推奨になりました。
サーバーアップグレードのチェックリスト
アップグレードの要件
既存のetcd環境を3.4にアップグレードするには、稼働中のクラスターが3.3以降でなければなりません。3.3より前の場合は、3.4にアップグレードする前に3.3にアップグレード してください。
また、ローリングアップグレードを円滑に進めるには、稼働中のクラスターが正常でなければなりません。作業を進める前に、etcdctl endpoint healthコマンドでクラスターの正常性を確認してください。
準備
etcdをアップグレードする際は、必ず本番環境に適用する前に、etcdに依存するサービスをステージング環境でテストしてください。
作業を始める前に、スナップショットバックアップをダウンロード
してください。アップグレードで問題が発生した場合は、このバックアップを使用して元のetcdバージョンにダウングレード
できます。snapshotコマンドでバックアップされるのはv3データのみであることに注意してください。v2データについては、v2データストアのバックアップ
を参照してください。
バージョンの混在
アップグレード中のetcdクラスターでは、異なるバージョンのetcdメンバーの混在がサポートされ、全メンバーに共通する最も低いバージョンのプロトコルで動作します。すべてのメンバーがバージョン3.4にアップグレードされて初めて、クラスターのアップグレードが完了したと見なされます。内部では、etcdメンバーが相互にネゴシエーションを行ってクラスター全体のバージョンを決定し、そのバージョンによって報告されるバージョンとサポートされる機能が決まります。
制限事項
注:クラスターにv3データしかなく、v2データがない場合、この制限は適用されません。
クラスターが50MBを超えるv2データセットを提供している場合、新しくアップグレードした各メンバーが既存のクラスターに追いつくまでに最大2分かかることがあります。直近のスナップショットのサイズを調べて、データの総量を見積もってください。つまり、各メンバーのアップグレードの間に2分待つのが最も安全です。
データの総量が100MB以上とさらに大きい場合、この1回限りの処理にはより長い時間がかかることがあります。この規模の非常に大きなetcdクラスターを管理している場合は、アップグレード前にetcdチーム までお気軽にお問い合わせください。手順についてアドバイスします。
ダウングレード
すべてのメンバーをv3.4にアップグレードすると、クラスターもv3.4にアップグレードされ、この完了状態からのダウングレードはできません。ただし、1つでもv3.3のメンバーが残っていれば、クラスターとその動作は「v3.3」のままであり、この混在状態からすべてのメンバーでv3.3のetcdバイナリを使用する状態に戻せます。
アップグレード完了後でもクラスターをダウングレードできるように、スナップショットバックアップをダウンロード してください。
アップグレード手順
この例では、ローカルマシンで稼働する3メンバー構成のv3.3 etcdクラスターをアップグレードする方法を説明します。
手順1:アップグレード要件の確認
クラスターは正常で、v3.3.xで稼働していますか。
手順2:リーダーからスナップショットバックアップをダウンロード
問題が発生した場合にダウングレードできるよう、スナップショットバックアップをダウンロード してください。
etcdのリーダーには最新のアプリケーションデータがあることが保証されているため、リーダーからスナップショットを取得します。
手順3:既存のetcdサーバーを1つ停止
各etcdプロセスを停止すると、他のクラスターメンバーに想定どおりのエラーが記録されます。クラスターメンバーへの接続が(一時的に)切断されたためであり、正常な動作です。
手順4:同じ設定でetcdサーバーを再起動
同じ設定で、新しいetcdバイナリを使用してetcdサーバーを再起動します。
新しいv3.4のetcdは、自身の情報をクラスターに公開します。この時点では、クラスターは引き続き全メンバーに共通する最も低いバージョンであるv3.3のプロトコルで動作します。
{"level":"info","ts":1526586617.1647713,"caller":"membership/cluster.go:485","msg":"set initial cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","cluster-version":"3.0"}
{"level":"info","ts":1526586617.1648536,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.0"}
{"level":"info","ts":1526586617.1649303,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","from":"3.0","from":"3.3"}
{"level":"info","ts":1526586617.1649797,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.3"}
{"level":"info","ts":1526586617.2107732,"caller":"etcdserver/server.go:1770","msg":"published local member to cluster through raft","local-member-id":"7339c4e5e833c029","local-member-attributes":"{Name:s1 ClientURLs:[http://localhost:2379]}","request-path":"/0/members/7339c4e5e833c029/attributes","cluster-id":"7dee9ba76d59ed53","publish-timeout":7}
新しいv3.4のetcdバイナリで、各メンバー、続いてクラスター全体が正常になることを確認してください。
クラスター全体のアップグレードが完了するまでは、未アップグレードのメンバーに次のような警告が記録されます。
これは想定された動作で、すべてのetcdクラスターメンバーをv3.4にアップグレードすると表示されなくなります。
手順5:残りのメンバーで手順3と手順4を繰り返す
すべてのメンバーのアップグレードが完了すると、クラスターは3.4へのアップグレードが成功したことを報告します。
メンバー1:
{"level":"info","ts":1526586949.0920913,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}{"level":"info","ts":1526586949.0921566,"caller":"etcdserver/server.go:2272","msg":"cluster version is updated","cluster-version":"3.4"}
メンバー2:
{"level":"info","ts":1526586949.092117,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"729934363faa4a24","from":"3.3","from":"3.4"}{"level":"info","ts":1526586949.0923078,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}
メンバー3:
{"level":"info","ts":1526586949.0921423,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"b548c2511513015","from":"3.3","from":"3.4"}{"level":"info","ts":1526586949.0922918,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}