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

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

マイナー バージョンのアップグレード（バージョン 1.16 から 1.17 など）とパッチリリースのアップグレード（1.17.0 から 1.17.1 など）のどちらにも同じ手順を使用します。

Apigee ハイブリッド バージョン 1.15 以前からアップグレードする場合は、ハイブリッド バージョン 1.17.1 にアップグレードする前に、まずバージョン 1.16 にアップグレードする必要があります。Apigee ハイブリッド バージョン 1.16 へのアップグレードの手順をご覧ください。

Apigee ハイブリッド v1.16 からの変更

次の変更点にご注意ください。

  • Model Context Protocol（MCP）のサポート: Apigee ハイブリッド バージョン 1.17 では、Model Context Protocol（MCP）のサポートが追加されました。これは、エージェント型 AI アプリケーションがマネージド MCP エンドポイントを介して API をツールとして使用できるようにするオープン プロトコルです。Apigee ハイブリッドは、他の API を管理するのと同じ方法でこれらの MCP ツール呼び出しをルーティング、承認、保護するため、独自の MCP サーバーを実行または維持する必要はありません。詳細については、Apigee の Model Context Protocol（MCP）の概要と MCP クイックスタートをご覧ください。
  • ルート CA 証明書のローテーション: Apigee ハイブリッド バージョン 1.17 では、ランタイム コンポーネント間の TLS 通信の信頼性を確保するルート認証局（CA）証明書のローテーションのサポートが追加されました。段階的なローテーション手順に沿って、ルート CA の有効期限が切れる前に、ダウンタイムなしでルート CA を置き換えることができるようになりました。詳細については、ルート CA 証明書をローテーションするをご覧ください。
  • TLS 1.3 のサポート: Apigee ハイブリッド バージョン 1.17 では、Transport Layer Security プロトコルの最新バージョンである TLS 1.3 のサポートが追加されています。TLS 1.3 は、以前の TLS バージョンよりも接続 handshake が高速で、セキュリティが強化されています。Ingress ゲートウェイで TLS を構成する方法については、Ingress ゲートウェイで TLS と mTLS を構成するをご覧ください。
  • AI ポリシーの転送プロキシのサポート: Apigee ハイブリッド バージョン 1.17 では、Model Armor やセマンティック キャッシュ ポリシーなどの AI ポリシーの転送プロキシのサポートが追加されています。これらのポリシーが行うアウトバウンド呼び出しを HTTP 転送プロキシ経由でルーティングできるようになりました。これは、以前のバージョンの Apigee ハイブリッドではサポートされていませんでした。詳細については、API プロキシの転送プロキシを構成するをご覧ください。
  • セマンティック キャッシュの Private Service Connect（PSC）エンドポイントのサポート: Apigee ハイブリッド バージョン 1.17 では、セマンティック キャッシュの Private Service Connect（PSC）エンドポイントのサポートが追加されています。セマンティック キャッシュ保存ポリシーは、Private Service Connect エンドポイントを介してバッキング サービスにアクセスできるようになりました。これにより、トラフィックはプライベート ネットワーク上に保持されます。詳細については、セマンティック キャッシュ保存ポリシーを使ってみるをご覧ください。

ハイブリッド バージョン 1.17 の機能の詳細については、Apigee ハイブリッド v1.17.1 リリースノートをご覧ください。

前提条件

ハイブリッド バージョン 1.17 にアップグレードする前に、インストールが次の要件を満たしていることを確認してください。

1.17.1 にアップグレードする前に - 制限事項と重要な注意事項

  • Apigee ハイブリッド バージョン 1.17 へのアップグレード中は、ダウンタイムが発生する場合があります。

    Apigee コントローラをバージョン 1.17.1 にアップグレードすると、すべての Apigee デプロイでローリング再起動が行われます。本番環境ハイブリッド環境のダウンタイムを最小限に抑えるには、少なくとも 2 つのクラスタ（同じまたは異なるリージョン/データセンター）を実行している必要があります。本番環境のすべてのトラフィックを 1 つのクラスタに戻し、オフラインでアップグレードしようとしているクラスタを取得して、アップグレード プロセスを続行します。この手順をクラスタごとに繰り返します。

    本番環境に影響する可能性を低減するため、アップグレードを開始した後できるだけ早くすべてのクラスタをアップグレードすることをおすすめします。最初のクラスタをアップグレードした後に、残りのすべてのクラスタをいつアップグレードする必要があるかについては、時間制限はありません。ただし、Cassandra のバックアップと復元はバージョンが混在している環境では機能しないため、残りのクラスタがすべてアップグレードされるまで使用できません。たとえば、ハイブリッド 1.16 のバックアップを使用してハイブリッド 1.17 のインスタンスを復元することはできません。

  • アップグレード中に管理プレーンの変更を完全に一時停止する必要はありません。管理プレーンの変更の一時停止が必要な場合は、以下のアップグレード手順に記載されています。

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

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

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

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

ハイブリッド インストールをバックアップする

  1. この手順では、ファイル システム内で Helm チャートをインストールしたディレクトリに対し、環境変数 APIGEE_HELM_CHARTS_HOME を使用します。必要に応じてこのディレクトリに移動し、次のコマンドで変数を定義します。

    Linux

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Mac OS 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Windows 

    set APIGEE_HELM_CHARTS_HOME=%CD%
echo %APIGEE_HELM_CHARTS_HOME%
  2. バージョン 1.16 の $APIGEE_HELM_CHARTS_HOME/ ディレクトリのバックアップを作成します。任意のバックアップ プロセスを使用できます。たとえば、次のコマンドを使用して、ディレクトリ全体の tar ファイルを作成します。
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Cassandra のバックアップと復元の手順に沿って Cassandra データベースをバックアップします。
  4. TLS 証明書ファイルと鍵ファイル（.crt、.key、.pem）が $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ ディレクトリにあることを確認します。

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

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

Apigee Helm チャートを pull します。

Apigee ハイブリッド チャートは Google Artifact Registry でホストされます。

oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts

次のコマンドで pull コマンドを使用して、すべての Apigee ハイブリッド Helm チャートをローカル ストレージにコピーします。

export CHART_REPO=oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
export CHART_VERSION=1.17.1
helm pull $CHART_REPO/apigee-operator --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-datastore --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-env --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-ingress-manager --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-org --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-redis --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-telemetry --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-virtualhost --version $CHART_VERSION --untar

カスタム Apigee Namespace の kustomization.yaml を編集する

Apigee Namespace が apigee でない場合は、apigee-operator/etc/crds/default/kustomization.yaml ファイルを編集して、namespace 値を Apigee Namespace に置き換えます。

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

Namespace として apigee を使用している場合は、ファイルを編集する必要はありません。

  • 更新された Apigee CRD をインストールします。

    1. 次のコマンドを実行して、kubectl ドライラン機能を使用します。

      kubectl apply -k  apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server

    2. dry-run コマンドで検証した後、次のコマンドを実行します。

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. kubectl get crds コマンドを使用してインストールを検証します。
      kubectl get crds | grep apigee

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

      apigeedatastores.apigee.cloud.google.com                    2024-08-21T14:48:30Z
apigeedeployments.apigee.cloud.google.com                   2024-08-21T14:48:30Z
apigeeenvironments.apigee.cloud.google.com                  2024-08-21T14:48:31Z
apigeeissues.apigee.cloud.google.com                        2024-08-21T14:48:31Z
apigeeorganizations.apigee.cloud.google.com                 2024-08-21T14:48:32Z
apigeeredis.apigee.cloud.google.com                         2024-08-21T14:48:33Z
apigeerouteconfigs.apigee.cloud.google.com                  2024-08-21T14:48:33Z
apigeeroutes.apigee.cloud.google.com                        2024-08-21T14:48:33Z
apigeetelemetries.apigee.cloud.google.com                   2024-08-21T14:48:34Z
cassandradatareplications.apigee.cloud.google.com           2024-08-21T14:48:35Z

  • クラスタノードのラベルを確認します。デフォルトでは、Apigee はラベルが cloud.google.com/gke-nodepool=apigee-data のノードでデータ Pod をスケジューリングし、ランタイム Pod はラベルが cloud.google.com/gke-nodepool=apigee-runtime のノードでスケジューリングされます。ノードプールのラベルは、overrides.yaml ファイルでカスタマイズできます。

    詳細については、専用ノードプールの構成をご覧ください。

    • cert-manager をアップグレードする

    Apigee ハイブリッド v1.17 は、cert-manager リリース 1.16 ～ 1.19 をサポートしています。cert-manager 1.18 には、トラフィックに問題を引き起こす可能性のある変更があります。cert-manager リリース 1.18 では、Certificate.Spec.PrivateKey.rotationPolicy のデフォルト値が Never から Always に変更されました。アップグレードされた Apigee ハイブリッド インストールの場合、これによりトラフィックに関する問題が発生する可能性があります。以前のバージョンからハイブリッド v1.17 にアップグレードする場合は、この変更を補うように apigee-ca 証明書を編集するか、cert-manager のバージョンをリリース 1.17.x 以下に維持する必要があります。

    cert-manager を 1.18 または 1.19 にアップグレードする前に、次の手順に沿って apigee-ca 証明書を編集し、Certificate.Spec.PrivateKey.rotationPolicy の値を Never に設定します。

    1. apigee-ca 証明書の内容を確認して、rotationPolicy が設定されているかどうかを確認します。 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      出力で spec.privateKey の下の値を探します。

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    # Note: rotationPolicy would appear here if it is set.
    size: 256
  secretName: apigee-ca
...
    2. rotationPolicy が設定されていない場合、または Always に設定されている場合は、apigee-ca 証明書を編集して rotationPolicy の値を Never に設定します。
      1. 最初にドライランを実行します。
        kubectl patch Certificate \
  --dry-run=server \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
      2. 証明書にパッチを適用します。
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. rotationPolicy の値が Never に設定されていることを確認します。
      kubectl get certificate apigee-ca -n cert-manager -o yaml

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

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    rotationPolicy: Never
    size: 256
  secretName: apigee-ca
...
    4. cert-manager をアップグレードします。次のコマンドは、cert-manager v1.19.2 をダウンロードしてインストールします。
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      サポートされているバージョンの一覧については、サポートされているプラットフォームとバージョン: cert-manager をご覧ください。

    参照:

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

    1. まだ行っていない場合は、APIGEE_HELM_CHARTS_HOME ディレクトリに移動します。このディレクトリから次のコマンドを実行します。
    2. Apigee Operator/Controller をアップグレードします。

      ドライランを実行します。

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      チャートをアップグレードします。

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Apigee Operator のインストールを確認します。

      helm ls -n APIGEE_NAMESPACE

      NAME       NAMESPACE       REVISION   UPDATED                                STATUS     CHART                   APP VERSION
operator   apigee   3          2024-08-21 00:42:44.492009 -0800 PST   deployed   apigee-operator-1.17.1   1.17.1

      可用性をチェックして、稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager

      NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
apigee-controller-manager   1/1     1            1           7d20h
    3. Apigee データストアをアップグレードします。

      ドライランを実行します。

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      チャートをアップグレードします。

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      状態をチェックして、apigeedatastore が稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

      NAME      STATE       AGE
default   running    2d
    4. Apigee テレメトリーをアップグレードします。

      ドライランを実行します。

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      チャートをアップグレードします。

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      状態をチェックして、稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

      NAME               STATE     AGE
apigee-telemetry   running   2d
    5. Apigee Redis をアップグレードします。

      ドライランを実行します。

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      チャートをアップグレードします。

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      状態をチェックして、稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get apigeeredis default

      NAME      STATE     AGE
default   running   2d
    6. Apigee Ingress Manager をアップグレードします。

      ドライランを実行します。

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      チャートをアップグレードします。

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      可用性をチェックして、稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get deployment apigee-ingressgateway-manager

      NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
apigee-ingressgateway-manager   2/2     2            2           2d
    7. Apigee 組織をアップグレードします。

      ドライランを実行します。

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      チャートをアップグレードします。

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      それぞれの組織の状態をチェックして、稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. 環境をアップグレードします。

      同時にインストールできる環境は 1 つだけです。--set env=ENV_NAME で環境を指定します。

      ドライランを実行します。

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server
      • ENV_RELEASE_NAME は、apigee-env チャートのインストールとアップグレードの追跡に使用する名前です。この名前は、インストール内の他の Helm リリース名と重複していない必要があります。通常、これは ENV_NAME と同じにします。ただし、環境と環境グループの名前が同じである場合は、環境と環境グループに対して異なるリリース名（dev-env-release と dev-envgroup-release など）を使用する必要があります。Helm でのリリースの詳細については、Helm ドキュメントの 3 つの大きなコンセプトをご覧ください。
      • ENV_NAME はアップグレードする環境の名前です。
      • OVERRIDES_FILE は、v.1.17.1 の新しいオーバーライド ファイルです。

      チャートをアップグレードします。

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE

      それぞれの環境の状態をチェックして、稼働していることを確認します。

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          running     2d
    9. 環境グループ（virtualhosts）をアップグレードします。
      1. 一度にアップグレードできる環境グループ（virtualhost）は 1 つだけです。--set envgroup=ENV_GROUP_NAME を使用して環境グループを指定します。overrides.yaml ファイルに記載されている環境グループごとに、次のコマンドを繰り返します。

        ドライランを実行します。

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server

        ENV_GROUP_RELEASE_NAME は、以前に apigee-virtualhost チャートをインストールしたときに使用した名前です。通常は ENV_GROUP_NAME です。

        チャートをアップグレードします。

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
      2. ApigeeRoute（AR）の状態を確認します。

        virtualhosts をインストールすると、ApigeeRouteConfig（ARC）が作成されます。これにより、Apigee ウォッチャーがコントロール プレーンから環境グループ関連の詳細を pull した時点で、ApigeeRoute（AR）が内部で作成されます。このため、対応する AR の状態が実行中であることを確認します。

        kubectl -n APIGEE_NAMESPACE get arc

        NAME                                STATE   AGE
apigee-org1-dev-egroup                       2d
         
        kubectl -n APIGEE_NAMESPACE get ar

        NAME                                        STATE     AGE
apigee-org1-dev-egroup-123abc               running   2d

    以前のバージョンにロールバックする

    以前のバージョンにロールバックするには、古いチャート バージョンを使用して、アップグレード プロセスを逆の順序でロールバックします。apigee-virtualhost から始めて apigee-operator までロールバックしてから、CRD を元に戻します。

    1. グラフを元に戻します。次のコマンドは、以前のバージョン（v1.16.x）のチャートを使用していることを前提としています。

      1. 環境グループごとに次のコマンドを実行します。

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=ENV_GROUP_NAME \
  -f 1.16_OVERRIDES_FILE

      2. 環境ごとに次のコマンドを実行します。

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=ENV_NAME \
  -f 1.16_OVERRIDES_FILE

      3. apigee-org:

        helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      4. apigee-ingress-manager:

        helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      5. apigee-redis:

        helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      6. apigee-telemetry:

        helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      7. apigee-datastore:

        helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      8. apigee-operator:

        helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE
    2. 古い CRD を再インストールして CRD を元に戻します。
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false