Apigee ハイブリッドのバージョン 1.10 へのアップグレード

この手順では、Apigee ハイブリッド バージョン 1.9.x から Apigee ハイブリッド バージョン 1.10.4 へのアップグレードと、ハイブリッド 1.10.x の以前のリリースからバージョン 1.10.4 へのアップグレードについて説明します。

マイナー バージョンのアップグレード(バージョン 1.9 から 1.10 など)とパッチリリース アップグレード(1.10.0 から 1.10.4 など)にも同じ手順を使用します。

バージョン 1.10.4 へのアップグレードの概要

以降のセクションでは、Apigee ハイブリッドのアップグレード手順を次の順番で説明します。

  1. アップグレードを準備する
  2. ハイブリッド ランタイムのバージョン 1.10.4 をインストールする

前提条件

以下のアップグレード手順は、Apigee ハイブリッド バージョン 1.9 x がインストールされており、バージョン 1.10.4 にアップグレードすることを前提としています。以前のバージョンから更新する場合は、Apigee ハイブリッド バージョン 1.9 へのアップグレードをご覧ください。

バージョン 1.10 へのアップグレードを準備する

  1. この手順では、apigeectl をインストールしたファイル システム内のディレクトリを環境変数 APIGEECTL_HOME で表しています。必要に応じて、ディレクトリを apigeectl ディレクトリに変更し、次のコマンドで変数を定義します。

    Linux

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    macOS

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    Windows

    set APIGEECTL_HOME=%CD%
    echo %APIGEECTL_HOME%
  2. バージョン 1.9 の $APIGEECTL_HOME/ ディレクトリのバックアップを作成します。次に例を示します。
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.9-backup.tar.gz $APIGEECTL_HOME
  3. Cassandra のバックアップと復元の手順に沿って Cassandra データベースをバックアップします。

Kubernetes のバージョンをアップグレードする

Kubernetes プラットフォームのバージョンを確認し、必要に応じて Kubernetes プラットフォームを、ハイブリッド 1.9 とハイブリッド 1.10 の両方でサポートされているバージョンにアップグレードします。ヘルプが必要な場合は、プラットフォームのドキュメントをご覧ください。

ハイブリッド 1.10.4 ランタイムをインストールする

  1. 現在のディレクトリがハイブリッド ベース ディレクトリ(apigeectl 実行可能ファイルが配置されているディレクトリの親)であることを確認します。
    cd $APIGEECTL_HOME/..
  2. 次のコマンドを使用して、ご使用のオペレーティング システムに対応したリリース パッケージをダウンロードします。ご利用のプラットフォームを次の表から選択します。

    Linux

    Linux 64 ビット:

    curl -LO \
      https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.10.4/apigeectl_linux_64.tar.gz

    macOS

    Mac 64 ビット:

    curl -LO \
      https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.10.4/apigeectl_mac_64.tar.gz

    Windows

    Windows 64 ビット:

    curl -LO ^
      https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.10.4/apigeectl_windows_64.zip
  3. 現在の apigeectl/ ディレクトリをバックアップ ディレクトリ名に変更します。次に例を示します。

    Linux

    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.9/

    macOS

    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.9/ 

    Windows

    rename %APIGEECTL_HOME% %APIGEECTL_HOME%-v1.9 
  4. ダウンロードした gzip ファイルの内容をハイブリッドのベース ディレクトリに展開します。ハイブリッドのベース ディレクトリは、名前を変更した apigeectl-v1.9 ディレクトリのあるディレクトリです。

    Linux

    tar xvzf filename.tar.gz -C ./

    macOS

    tar xvzf filename.tar.gz -C ./

    Windows

    tar xvzf filename.zip -C ./
  5. デフォルトでは、tar の内容が展開されるディレクトリの名前には、バージョンとプラットフォームが含まれています。たとえば、./apigeectl_1.10.4-xxxxxxx_linux_64 となります。次のコマンドを使用して、このディレクトリの名前を apigeectl に変更します。

    Linux

    mv apigeectl_1.10.4-xxxxxxx_linux_64 apigeectl

    macOS

    mv apigeectl_1.10.4-xxxxxxx_mac_64 apigeectl

    Windows

    rename apigeectl_1.10.4-xxxxxxx_windows_64 apigeectl
  6. apigeectl ディレクトリに移動します。
    cd ./apigeectl

    このディレクトリは apigeectl ホーム ディレクトリになります。apigeectl 実行可能コマンドはこのディレクトリに配置されます。

  7. この手順では、apigeectl ユーティリティがインストールされているファイル システムのディレクトリを環境変数 $APIGEECTL_HOME で表しています。必要に応じて、ディレクトリを apigeectl ディレクトリに変更し、次のコマンドで変数を定義します。

    Linux

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    macOS

    export APIGEECTL_HOME=$PWD
    echo $APIGEECTL_HOME

    Windows

    set APIGEECTL_HOME=%CD%
    echo %APIGEECTL_HOME%
  8. version コマンドで apigeectl のバージョンを確認します。
    ./apigeectl version
    Version: 1.10.4
  9. hybrid-base-directory/hybrid-files ディレクトリを作成し、そのディレクトリに移動します。hybrid-files ディレクトリには、オーバーライド ファイル、証明書、サービス アカウントなどの構成ファイルがあります。次に例を示します。

    Linux

    mkdir $APIGEECTL_HOME/../hybrid-files
    cd $APIGEECTL_HOME/../hybrid-files

    macOS

    mkdir $APIGEECTL_HOME/../hybrid-files
    cd $APIGEECTL_HOME/../hybrid-files

    Windows

    mkdir %APIGEECTL_HOME%/../hybrid-files
    cd %APIGEECTL_HOME%/../hybrid-files
  10. 次のコマンドを使用して、kubectl が正しいコンテキストに設定されていることを確認します。現在のコンテキストは、Apigee ハイブリッドをアップグレードするクラスタに設定する必要があります。
    kubectl config get-contexts | grep \*
  11. hybrid-files ディレクトリ:
    1. 以下の $APIGEECTL_HOME へのシンボリック リンクを更新します。このリンクを使用すると、hybrid-files ディレクトリ内から新しくインストールされた apigeectl コマンドを実行できます。
      ln -nfs $APIGEECTL_HOME/tools tools
      ln -nfs $APIGEECTL_HOME/config config
      ln -nfs $APIGEECTL_HOME/templates templates
      ln -nfs $APIGEECTL_HOME/plugins plugins
    2. シンボリック リンクが正しく作成されたことを確認するには、次のコマンドを実行してリンクパスが正しい場所を指していることを確認します。
      ls -l | grep ^l
  12. ドライランの初期化を行ってエラーを確認します。
    ${APIGEECTL_HOME}/apigeectl init -f OVERRIDES_FILE --dry-run=client

    ここで、OVERRIDES_FILE はオーバーライド ファイルの名前です(例: ./overrides/overrides.yaml)。

  13. エラーがなければ、ハイブリッド 1.10.4 を初期化します。
    $APIGEECTL_HOME/apigeectl init -f OVERRIDES_FILE
  14. 初期化のステータスを確認します。
    $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

    成功すると、「All containers ready.」と出力されます。

    kubectl describe apigeeds -n apigee

    出力で「State: running」を探します。

  15. --dry-run フラグを使用して、apply コマンドのドライランでエラーを確認します。
    $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --dry-run=client
  16. エラーがない場合、オーバーライドを適用します。インストールに応じて、本番環境または非本番環境用の手順を実施します。

    本番環境

    本番環境では、ハイブリッド コンポーネントを個別にアップグレードし、アップグレードされたコンポーネントのステータスを確認してから次のコンポーネントに進んでください。

    1. 現在のディレクトリが hybrid-files ディレクトリであることを確認します。
    2. オーバーライドを適用して Cassandra をアップグレードします。
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --datastore
    3. 完了を確認します。
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

      Pod の準備ができた場合にのみ、次の手順に進みます。

    4. オーバーライドを適用してテレメトリー コンポーネントをアップグレードし、完了を確認します。
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --telemetry
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
    5. Redis コンポーネントを起動します。
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --redis
    6. オーバーライドを適用して、組織レベルのコンポーネント(MART、Watcher、Apigee Connect)をアップグレードし、完了を確認します。
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --org
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
    7. オーバーライドを適用して環境をアップグレードします。次の 2 つの選択肢があります。
      • 環境ごと: 一度に 1 つの環境にオーバーライドを適用して、完了を確認します。この手順を環境ごとに繰り返します。
        $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --env ENV_NAME
        $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

        ここで、ENV_NAME はアップグレードする環境の名前です。

      • 一度にすべての環境: すべての環境にオーバーライドを一度に適用して、完了を確認します。
        $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --all-envs
        $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
    8. オーバーライドを適用して virtualhosts コンポーネントをアップグレードし、完了を確認します。
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --settings virtualhosts
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

    非本番環境

    非本番環境、デモ環境、試験運用版環境の大半では、すべてのコンポーネントに同時にオーバーライドを適用できます。非本番環境が大規模で複雑な場合や、本番環境とよく似ている場合は、本番環境をアップグレードするための手順の実施をおすすめします。

    1. 現在のディレクトリが hybrid-files ディレクトリであることを確認します。
    2. $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE
    3. ステータスを確認します。
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

アップグレードのロールバック

以前のアップグレードをロールバックする手順は次のとおりです。

  1. ハイブリッド ランタイムの名前空間に対して、完了したジョブのクリーンアップを行います。ここで、名前空間を指定した場合、NAMESPACE はオーバーライド ファイルで指定した名前空間になります。指定しない場合、デフォルトの名前空間は apigee です。
    kubectl delete job -n NAMESPACE \
      $(kubectl get job -n NAMESPACE \
      -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')
  2. apigee-system 名前空間で完了したジョブをクリーンアップします。
    kubectl delete job -n apigee-system \
      $(kubectl get job -n apigee-system \
      -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')
  3. 以前のバージョンの apigeectl を含むディレクトリを指すように APIGEECTL_HOME 変数を変更します。次に例を示します。
    export APIGEECTL_HOME=PATH_TO_PREVIOUS_APIGEECTL_DIRECTORY
  4. ロールバックするインストールのルート ディレクトリで、apigeectl apply を実行し、Pod のステータスを確認してから apigeectl init を実行します。ロールバックするバージョンの元のオーバーライド ファイルを必ず使用してください。
    1. ハイブリッド ファイル ディレクトリで、apigeectl apply を実行します。
      $APIGEECTL_HOME/apigeectl apply -f ORIGINAL_OVERRIDES_FILE

      ここで、ORIGINAL_OVERRIDES_FILE は、以前のバージョンのハイブリッド インストールのオーバーライド ファイルの相対パスとファイル名です(例: ./overrides/overrides1.9.yaml)。

    2. Pod のステータスを確認します。
      kubectl -n NAMESPACE get pods

      ここで、NAMESPACE は Apigee ハイブリッドの名前空間です。

    3. apigeeds のステータスを確認します。
      kubectl describe apigeeds -n apigee

      出力は次のようになります。

      Status:
        Cassandra Data Replication:
        Cassandra Pod Ips:
          10.8.2.204
        Cassandra Ready Replicas:  1
        Components:
          Cassandra:
            Last Successfully Released Version:
              Revision:  v1-f8aa9a82b9f69613
              Version:   v1
            Replicas:
              Available:  1
              Ready:      1
              Total:      1
              Updated:    1
            State:        running
        Scaling:
          In Progress:         false
          Operation:
          Requested Replicas:  0
        State:                 running
      

      apigeeds Pod が実行されている場合にのみ、次の手順に進みます。

    4. 次のコマンドを実行して、アップグレード後に Message Processor の新しいレプリカ数の値をメモします。これらの値が、以前に構成した値と一致しない場合は、オーバーライド ファイルの値を以前の構成と一致するように変更します。
      apigeectl apply -f ORIGINAL_OVERRIDES_FILE --dry-run=client --print-yaml --env ENV_NAME 2>/dev/null |grep "runtime:" -A 25 -B 1| grep "autoScaler" -A 2

      出力は次のようになります。

            autoScaler:
              minReplicas: 2
              maxReplicas: 10
    5. apigeectl init を実行します。
      $APIGEECTL_HOME/apigeectl init -f ORIGINAL_OVERRIDES_FILE