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

ここでは、Apigee ハイブリッド バージョン 1.12.x から Apigee ハイブリッド バージョン 1.13.1 へのアップグレードについて説明します。

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

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

  • Apigee Namespace の apigee-operator: バージョン 1.13 以降、apigee-operator は他の Apigee ハイブリッド コンポーネントと同じ Kubernetes Namespace（デフォルトは apigee）で実行されます。Namespace には任意の名前を指定できます。以前のバージョンでは、apigee-operator は独自の Namespace apigee-system で実行する必要がありました。
  • Anthos（ベアメタルまたは VMware）は Google Distributed Cloud（ベアメタルまたは VMware）になりました。詳細については、ベアメタル版 Google Distributed Cloud と VMware 用 Google Distributed Cloud のプロダクト概要をご覧ください。

前提条件

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

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

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

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

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

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

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

    Linux

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    macOS 

    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.12 の $APIGEE_HELM_CHARTS_HOME/ ディレクトリのバックアップを作成します。任意のバックアップ プロセスを使用できます。たとえば、次のコマンドを使用して、ディレクトリ全体の tar ファイルを作成します。
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.12-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Cassandra のバックアップと復元の手順で Cassandra データベースをバックアップします。
  4. オーバーライドでサービス証明書ファイル（.json）を使用してサービス アカウントを認証している場合は、サービス アカウント証明書ファイルが正しい Helm チャート ディレクトリにあることを確認してください。Helm チャートは、各チャート ディレクトリ外のファイルを読み取ることができません。

    Kubernetes Secret または Workload Identity を使用してサービス アカウントを認証している場合は、この手順は必要ありません。

    次の表に、インストールの種類に応じた各サービス アカウント ファイルの移動先を示します。

    本番環境

    サービス アカウント デフォルトのファイル名 Helm チャートのディレクトリ
    apigee-cassandra PROJECT_ID-apigee-cassandra.json $APIGEE_HELM_CHARTS_HOME/apigee-datastore/
    apigee-logger PROJECT_ID-apigee-logger.json $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    apigee-mart PROJECT_ID-apigee-mart.json $APIGEE_HELM_CHARTS_HOME/apigee-org/
    apigee-metrics PROJECT_ID-apigee-metrics.json $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    apigee-runtime PROJECT_ID-apigee-runtime.json $APIGEE_HELM_CHARTS_HOME/apigee-env
    apigee-synchronizer PROJECT_ID-apigee-synchronizer.json $APIGEE_HELM_CHARTS_HOME/apigee-env/
    apigee-udca PROJECT_ID-apigee-udca.json $APIGEE_HELM_CHARTS_HOME/apigee-org/
    apigee-watcher PROJECT_ID-apigee-watcher.json $APIGEE_HELM_CHARTS_HOME/apigee-org/

    非本番環境

    次の各ディレクトリに、apigee-non-prod サービス アカウント ファイルのコピーを作成します。

    サービス アカウント デフォルトのファイル名 Helm チャートのディレクトリ
    apigee-non-prod PROJECT_ID-apigee-non-prod.json $APIGEE_HELM_CHARTS_HOME/apigee-datastore/
    $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    $APIGEE_HELM_CHARTS_HOME/apigee-org/
    $APIGEE_HELM_CHARTS_HOME/apigee-env/
  5. TLS 証明書ファイルと鍵ファイル（.crt、.key、.pem）が $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ ディレクトリにあることを確認します。

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

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

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

Helm チャートのアップグレードを準備する

  1. 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.13.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
  2. 必要に応じて cert-manager をアップグレードします。

    cert-manager のバージョンをアップグレードする必要がある場合は、次のコマンドを使用して、新しいバージョンをインストールします。

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.yaml

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

  3. 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 を使用している場合は、ファイルを編集する必要はありません。

  4. 更新された 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
  5. apigee-operator を apigee-system Namespace から APIGEE_NAMESPACE に移行します。
    1. 新しい Namespace で clusterIssuer にアノテーションを付けます。
      kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='APIGEE_NAMESPACE'
    2. apigee-operator のリリース名を変更する場合は、clusterIssuer に新しいリリース名でアノテーションを付けます。
      kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-name='APIGEE_OPERATOR_RELEASE_NAME'
  6. 2 つのコントローラが調整されないように、apigee-system Namespace 内の既存の Apigee Operator デプロイのレプリカを 0（ゼロ）に更新します。
    kubectl scale deployment apigee-controller-manager -n apigee-system --replicas=0
  7. 2 つのコントローラが調整されないように、apigee-system Namespace 内の既存の Apigee Operator デプロイのレプリカを 0（ゼロ）に更新します。
    kubectl delete mutatingwebhookconfiguration apigee-mutating-webhook-configuration
kubectl delete validatingwebhookconfiguration apigee-validating-webhook-configuration

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

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

Apigee ハイブリッド Helm チャートをインストールする

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

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

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

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

    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.13.1   1.13.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

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

    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

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

    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

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

    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

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

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

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

    kubectl -n APIGEE_NAMESPACE get apigeeorg

    NAME                      STATE     AGE
apigee-org1-xxxxx          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
    • ENV_RELEASE_NAME は、以前に apigee-env チャートをインストールしたときに使用した名前です。ハイブリッド v1.10 では通常、apigee-env-ENV_NAME です。ハイブリッド v1.11 以降では、通常は ENV_NAME です。
    • ENV_NAME はアップグレードする環境の名前です。
    • OVERRIDES_FILE は、v.1.13.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-org1-dev-xxx            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

      ENV_GROUP_RELEASE_NAME は、以前に apigee-virtualhost チャートをインストールしたときに使用した名前です。ハイブリッド v1.10 では通常、apigee-virtualhost-ENV_GROUP_NAME です。ハイブリッド v1.11 以降では、通常は 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-xxxxxx                running   2d
  10. すべてのインストールが正常にアップグレードされたことを確認したら、古い apigee-operator リリースを apigee-system Namespace から削除します。
    1. 古い operator リリースをアンインストールします。
      helm delete operator -n apigee-system
    2. apigee-system Namespace を削除します。
      kubectl delete namespace apigee-system
  11. Apigee Namespace で operator を再度アップグレードして、削除されたクラスタ スコープのリソースを再インストールします。
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

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

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

apigee-operator の Namespace が変更されたため、Validating と Mutating のアドミッション フックを削除するには追加の手順が必要です。これにより、apigee-operator を apigee-system Namespace に再インストールすると、正しい Apigee Operator エンドポイントを参照するように再作成されます。

  1. Apigee で既存の Apigee Operator デプロイのレプリカを 0（ゼロ）に更新します。これにより、2 つのコントローラがカスタム リソースを調整しなくなり、apigee-system Namespace でロールバックするときに競合が発生しなくなります。
    kubectl scale deployment apigee-controller-manager -n APIGEE_NAMESPACE --replicas=0

kubectl delete mutatingwebhookconfiguration \
  apigee-mutating-webhook-configuration-APIGEE_NAMESPACE

kubectl delete validatingwebhookconfiguration \
  apigee-validating-webhook-configuration-APIGEE_NAMESPACE
  2. すべてのチャートを apigee-virtualhost から apigee-datastore に戻します。次のコマンドは、以前のバージョン（v1.12.x）のチャートを使用していることを前提としています。

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

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

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

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

    apigee-operator を除く残りのチャートを元に戻します。

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

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

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

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

    helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.12_OVERRIDES_FILE
  3. apigee-system Namespace を作成します。
    kubectl create namespace apigee-system
  4. リソース アノテーションを apigee-system Namespace に適用します。
    kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='apigee-system'
  5. リリース名も変更した場合は、operator リリース名でアノテーションを更新します。
    kubectl annotate --overwrite cluseterIssuer apigee-ca-issuer meta.helm.sh/release-name='operator'
  6. apigee-operator を apigee-system Namespace に再インストールします。
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace apigee-system \
  --atomic \
  -f 1.12_OVERRIDES_FILE
  7. 古い CRD を再インストールして CRD を元に戻します。
    kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
  8. APIGEE_NAMESPACE Namespace から apigee-operator リリースをクリーンアップして、ロールバック プロセスを完了します。
    helm uninstall operator -n APIGEE_NAMESPACE
  9. clusterIssuer などのクラスタ スコープのリソースは、operator がアンインストールされると削除されます。次のコマンドを使用して再インストールします。
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace apigee-system \
  --atomic \
  -f 1.12_OVERRIDES_FILE