3.17. 2.9.5 から 3.0.5 へのアップグレード

2.9.5 から 3.0.5 へのアップグレードでは、Red Hat Quay がダウンしている状態で全アップグレードを行う (同時アップグレード) か、Red Hat Quay を数分間だけダウンさせて、アップグレードの大部分は Red Hat Quay が稼働している状態で行う (バックグラウンドアップグレード) かを選択できます。

処理する必要のあるタグの数によっては、バックグラウンドアップグレードの実行に時間がかかる場合があります。ただし、合計ダウンタイムは短くなります。バックグラウンドアップグレードの欠点は、アップグレードが完了するまで最新の機能にアクセスできないことです。クラスターは、アップグレードが完了するまで、Quay v3 コンテナーから v2 互換モードで実行されます。

3.17.1. アップグレードの概要

Red Hat Quay 2.y.z クラスターで作業を開始する場合は、以下の手順に従います。最新の Red Hat Quay 3.x バージョンにアップグレードする前に、ここ で説明されているように、まずそのクラスターを 3.0.5 に移行する必要があります。クラスターで 3.0.5 が実行されたら、各マイナーバージョンに順番にアップグレードすることで、最新の 3.x バージョンにアップグレードできます。以下に例を示します。

  1. 3.0.5 → 3.1.3
  2. 3.1.3 → 3.2.2
  3. 3.2.2 → 3.3.4
  4. 3.3.4 → 3.4.z

Red Hat Quay 2.y.z から 3.0 へのアップグレードを開始する前に、次の点に注意してください。

  • 同期アップグレード: 同期アップグレードの場合は、小規模なインストールであれば、ダウンタイムの想定時間は合計 1 時間未満となっています。小規模なインストールの場合は、コンテナーイメージのタグが数千以下であると想定してください。このサイズのインストールでは、計画ダウンタイムが 2 時間程度に抑えられるはずです。Red Hat Quay サービス全体がこの期間、停止しているので、何百万ものタグが含まれるレジストリーで同期アップグレードを試行する場合はダウンタイムが数日間に及ぶ場合があります。
  • バックグラウンドアップグレード: バックグラウンドアップグレード (互換性モードのアップグレードとも呼ばれる) の場合は、シャットダウンが短時間で行われた後に Red Hat Quay クラスターのアップグレードがバックグラウンドで実行されます。大規模な Red Hat Quay レジストリーの場合、これには数週間の時間がかかる可能性がありますが、アップグレード中には、クラスターは引き続き v2 モードで動作します。参考までに、ある Red Hat Quay v3 のアップグレードでは、6 台のマシンで約 3000 万個のタグを処理するのに 4 日かかりました。
  • 完了時に完全な機能: Docker バージョン 2、スキーマ 2 の変更に伴う機能 (異なるアーキテクチャーのコンテナーのサポートなど) にアクセスするには、移行がすべて完了している必要があります。その他の v3 機能は、切り替え後すぐに利用できます。
  • アップグレードの完了: アップグレードが完了したら、新機能が利用可能になるように Red Hat Quay config.yaml ファイルで V3_UPGRADE_MODE: complete を設定する必要があります。すべての新しい Red Hat Quay v3 のインストールには、自動的にこの設定がされています。

3.17.2. 前提条件

最善の結果が得られるように、以下の前提条件を満たすことを推奨します。

  • アップグレードを開始する前に Red Hat Quay データベースをバックアップしておきます (定期的なバックアップを実行するのが一般的なベストプラクティスです)。バックアップは、アップグレードを行うために Red Hat Quay クラスターを停止した直後が適切なタイミングです。
  • ストレージをバックアップします (こちらも一般的なベストプラクティス)。
  • V3 のアップグレードを開始する前に、現在の Red Hat Quay 2.y.z 設定を最新の 2.9.z バージョン (現時点では 2.9.5) にアップグレードします。これを実行するには、以下を行います。

    • Red Hat Quay クラスターがまだ実行中の間に、ノード 1 つを取り、そのシステムの Quay コンテナーを最新の 2.9.z バージョンを実行している Quay コンテナーに変更します。
    • すべてのデータベース移行の実行を待機し、データベースを最新の 2.9.z バージョンにします。これには数分から 1 時間かかります。
    • 完了したら、すべての既存ノードの Quay コンテナーを、同じ最新の 2.9.z バージョンに置き換えます。新規バージョンの Red Hat Quay クラスター全体で、v3 アップグレードに進むことができます。

3.17.3. アップグレードタイプの選択

同期アップグレード (ダウンタイムでアップグレードを完了) か、バックグラウンドアップグレード (Red Hat Quay の実行中にアップグレードを完了) のいずれかを選択します。これらのメジャーリリースのアップグレードでは、Red Hat Quay クラスターを少なくとも短期間停止する必要があります。

選択したアップグレードのタイプを問わず、ビルダーおよび clair イメージを使用している場合は、Red Hat Quay クラスターが停止している間に、ビルダーおよび Clair を新規イメージにアップグレードする必要があります。

  • Builder: quay.io/redhat/quay-builder:v3.0.5
  • Clair: quay.io/redhat/clair-jwt:v3.0.5

これらのイメージはいずれも registry.redhat.io/quay リポジトリーから入手できます。

3.17.4. 同期アップグレードの実行

同期アップグレード (アップグレード中にクラスター全体が停止する) を実行するには、以下を実行します。

  1. Quay-builder および Clair コンテナーなど Red Hat Quay クラスター全体で停止します。
  2. 以下の設定を全ノードの config.yaml ファイルに追加します。

    V3_UPGRADE_MODE: complete

  3. 単一ノードで v3 コンテナーをプルおよび起動して、アップグレードが完了するのを待ちます (数分で完了するはずです)。以下のコンテナーのバージョンより新しいものを使用します。

    • Quay: quay.io/redhat/quay:v3.0.5

      Quay コンテナーは、Red Hat Quay 2 の場合のように 80 および 443 ではなく、Red Hat Quay 3 のポート 8080 および 8443 で起動することに注意してください。したがって、以下の例のように 8080 および 8443 をそれぞれ 80 および 443 に再マッピングすることを推奨します。

    # docker run --restart=always -p 80:8080 -p 443:8443 \
       --sysctl net.core.somaxconn=4096 \
       --privileged=true \
       -v /mnt/quay/config:/conf/stack:Z \
       -v /mnt/quay/storage:/datastorage:Z \
       -d quay.io/redhat/quay:v3.0.5
  4. アップグレードが完了したら、他のすべてのノードで Red Hat Quay 3 コンテナーを起動します。
  5. quay-builder と Clair の 3.0.z バージョンを起動して、クラスターに戻すコンテナーのインスタンスを置き換えます。
  6. Docker バージョン 2、スキーマ 2 と互換性のあるコンテナーのプッシュおよびプルなど、Red Hat Quay が機能していることを確認します。これには、Windows コンテナーイメージおよび異なるコンピューターアーキテクチャーのイメージ (arm、ppc など) が含まれます。

3.17.5. バックグラウンドアップグレードの実行

バックグラウンドアップグレードは、2 回ほどクラスターを短時間ダウンさせるだけで実行できます。最初のダウンタイム後にクラスターを再起動すると、データベースをバックフィルするため、quay v3 コンテナーは v2 互換性モードで実行します。このバックグラウンドプロセスが完了するまでに時間または数日かかる場合があります。数時間を超えるダウンタイムが問題となるような大規模なインストールを行う場合は、バックグラオウンドアップグレードが推奨されます。

このタイプのアップグレードでは、Red Hat Quay を互換性モードにします。互換性モードでは、Quay 3 コンテナーが実行しますが、アップグレードが完了するまで以前のデータモデルで実行します。手順は以下のとおりです。

  1. Red Hat Quay 3 コンテナーをすべてのノードにプルします。以下のコンテナーのバージョンより新しいものを使用します。

    quay.io/redhat/quay:v3.0.5

  2. Quay-builder および Clair コンテナーなど Red Hat Quay クラスター全体で停止します。
  3. 各ノードで config.yaml ファイルを編集し、以下のようにアップグレードモードを background に設定します。

    V3_UPGRADE_MODE: background

  4. Red Hat Quay 3 コンテナーを単一ノードで起動し、移行が完了するまで待機します (最大で数分かかります)。以下はコマンドの例です。

    Quay コンテナーは、Red Hat Quay 2 の場合のように 80 および 443 ではなく、Red Hat Quay 3 のポート 8080 および 8443 で起動することに注意してください。したがって、以下の例のように 8080 および 8443 をそれぞれ 80 および 443 に再マッピングすることを推奨します。

    # docker run --restart=always -p 80:8080 -p 443:8443 \
       --sysctl net.core.somaxconn=4096 \
       --privileged=true \
       -v /mnt/quay/config:/conf/stack:Z \
       -v /mnt/quay/storage:/datastorage:Z \
       -d quay.io/redhat/quay:v3.0.5
  5. その他のすべてのノードで Red Hat Quay 3 コンテナーを起動します。
  6. 次の手順に進むのに十分なレポーティングがされるまで (ステータスが 99% に到達するまで)、/upgradeprogress API エンドポイントを監視します。たとえば https://myquay.example.com/upgradeprogress を表示するか、他のツールを使用して API をクエリーします。
  7. バックグラウンドプロセスが十分に終了したら、別のメンテナンス期間をスケジュールする必要があります。
  8. 定期メンテナンス時に、Red Hat Quay クラスター全体を停止します。
  9. 各ノードで config.yaml ファイルを編集し、以下のように、アップグレードモードを complete に設定します。

    V3_UPGRADE_MODE: complete
  10. Red Hat Quay を 1 つのノードで再び起動し、最終チェックを実行できるようにします。
  11. 最終チェックが完了したら、Red Hat Quay v3 を他のすべてのノードでも起動します。
  12. quay-builder と Clair の 3.0.z バージョンを起動して、クラスターに戻すコンテナーのインスタンスを置き換えます。
  13. Docker バージョン 2、スキーマ 2 と互換性のあるコンテナーのプッシュおよびプルなど、Quay が機能していることを確認します。これには、Windows コンテナーイメージおよび異なるコンピューターアーキテクチャーのイメージ (arm、ppc など) が含まれます。

3.17.6. ターゲットイメージ

  • Quay: quay.io/redhat/quay:v3.0.5
  • Clair: quay.io/redhat/clair-jwt:v3.0.5
  • Redis: registry.access.redhat.com/rhscl/redis-32-rhel7
  • PostgreSQL: rhscl/postgresql-96-rhel7
  • Builder: quay.io/redhat/quay-builder:v3.0.5