ここでは、Apigee ハイブリッド バージョン 1.12.x から Apigee ハイブリッド バージョン 1.13.0 へのアップグレードについて説明します。
Apigee ハイブリッド v1.12 からの変更
次の変更点にご注意ください。
-
Apigee Namespace の
apigee-operator
: バージョン 1.13 以降、apigee-operator
は他の Apigee ハイブリッド コンポーネントと同じ Kubernetes Namespace(デフォルトはapigee
)で実行されます。Namespace には任意の名前を指定できます。以前のバージョンでは、apigee-operator
は独自の Namespaceapigee-system
で実行する必要がありました。 - Anthos(ベアメタルまたは VMware)は Google Distributed Cloud(ベアメタルまたは VMware)になりました。詳細については、ベアメタル版 Google Distributed Cloud と VMware 用 Google Distributed Cloud のプロダクト概要をご覧ください。
前提条件
ハイブリッド バージョン 1.13 にアップグレードする前に、インストールが次の要件を満たしていることを確認してください。
- ハイブリッド インストールで v1.12 より前のバージョンを実行している場合は、v1.13 にアップグレードする前にバージョン 1.12 にアップグレードする必要があります。Apigee ハイブリッド バージョン 1.12 へのアップグレードをご覧ください。
- Helm バージョン v3.10 以降。
kubectl
バージョン 1.27、1.28、1.29(推奨)。- cert-manager バージョン v1.15.1。必要に応じて、後述のバージョンへのアップグレードの準備で cert-manager をアップグレードします。
バージョン 1.13.0 へのアップグレードの概要
以降のセクションでは、Apigee Hybrid のアップグレード手順を次の順番で説明します。
バージョン 1.13 へのアップグレードを準備する
ハイブリッド インストールをバックアップする
- この手順では、ファイル システム内で 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%
- バージョン 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
- Cassandra のバックアップと復元の手順で Cassandra データベースをバックアップします。
- オーバーライドでサービス証明書ファイル(
.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/
-
TLS 証明書ファイルと鍵ファイル(
.crt
、.key
、.pem
)が$APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/
ディレクトリにあることを確認します。
Kubernetes のバージョンをアップグレードする
Kubernetes プラットフォームのバージョンを確認し、必要に応じて Kubernetes プラットフォームを、ハイブリッド 1.12 とハイブリッド 1.13 の両方でサポートされているバージョンにアップグレードします。ヘルプが必要な場合は、プラットフォームのドキュメントをご覧ください。
ハイブリッド 1.13.0 ランタイムをインストールする
Helm チャートのアップグレードを準備する
- 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.0
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
- 必要に応じて cert-manager をアップグレードします。
cert-manager のバージョンをアップグレードする必要がある場合は、次のコマンドを使用して、新しいバージョンをインストールします。
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.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 をインストールします。
-
次のコマンドを実行して、
kubectl
ドライラン機能を使用します。kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server
-
dry-run コマンドで検証した後、次のコマンドを実行します。
kubectl apply -k apigee-operator/etc/crds/default/ \ --server-side \ --force-conflicts \ --validate=false
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-operator
をapigee-system
Namespace から APIGEE_NAMESPACE に移行します。- 新しい Namespace で
clusterIssuer
にアノテーションを付けます。kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='APIGEE_NAMESPACE'
apigee-operator
のリリース名を変更する場合は、clusterIssuer
に新しいリリース名でアノテーションを付けます。kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-name='APIGEE_OPERATOR_RELEASE_NAME'
- 新しい Namespace で
- 2 つのコントローラが調整されないように、
apigee-system
Namespace 内の既存の Apigee Operator デプロイのレプリカを 0(ゼロ)に更新します。kubectl scale deployment apigee-controller-manager -n apigee-system --replicas=0
- 2 つのコントローラが調整されないように、
apigee-system
Namespace 内の既存の Apigee Operator デプロイのレプリカを 0(ゼロ)に更新します。kubectl delete mutatingwebhookconfiguration apigee-mutating-webhook-configuration
kubectl delete validatingwebhookconfiguration apigee-validating-webhook-configuration
-
クラスタノードの既存のラベルを確認します。デフォルトでは、Apigee はラベルが
cloud.google.com/gke-nodepool=apigee-data
のノードでデータ Pod をスケジューリングし、ランタイム Pod はラベルがcloud.google.com/gke-nodepool=apigee-runtime
のノードでスケジューリングされます。ノードプールのラベルは、overrides.yaml
ファイルでカスタマイズできます。詳細については、専用ノードプールの構成をご覧ください。
Apigee ハイブリッド Helm チャートをインストールする
- まだ行っていない場合は、
APIGEE_HELM_CHARTS_HOME
ディレクトリに移動します。このディレクトリから次のコマンドを実行します。 - 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.0 1.13.0
可用性をチェックして、稼働していることを確認します。
kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager
NAME READY UP-TO-DATE AVAILABLE AGE apigee-controller-manager 1/1 1 1 7d20h
- Apigee データストアをアップグレードします。
ドライランを実行します。
helm upgrade datastore apigee-datastore/ \ --install \ --namespace APIGEE_NAMESPACE \ -f OVERRIDES_FILE \ --dry-run
チャートをアップグレードします。
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
- 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
- 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
- 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
- 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
- 環境をアップグレードします。
同時にインストールできる環境は 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.0 の新しいオーバーライド ファイルです。
チャートをアップグレードします。
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
- ENV_RELEASE_NAME は、以前に
-
環境グループ(
virtualhosts
)をアップグレードします。- 一度にアップグレードできる環境グループ(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
- 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
- 一度にアップグレードできる環境グループ(virtualhost)は 1 つだけです。
- すべてのインストールが正常にアップグレードされたことを確認したら、古い
apigee-operator
リリースをapigee-system
Namespace から削除します。- 古い
operator
リリースをアンインストールします。helm delete operator -n apigee-system
apigee-system
Namespace を削除します。kubectl delete namespace apigee-system
- 古い
- 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 エンドポイントを参照するように再作成されます。
- 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
- すべてのチャートを
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
apigee-system
Namespace を作成します。kubectl create namespace apigee-system
- リソース アノテーションを
apigee-system
Namespace に適用します。kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='apigee-system'
- リリース名も変更した場合は、
operator
リリース名でアノテーションを更新します。kubectl annotate --overwrite cluseterIssuer apigee-ca-issuer meta.helm.sh/release-name='operator'
apigee-operator
をapigee-system
Namespace に再インストールします。helm upgrade operator apigee-operator/ \ --install \ --namespace apigee-system \ --atomic \ -f 1.12_OVERRIDES_FILE
- 古い CRD を再インストールして CRD を元に戻します。
kubectl apply -k apigee-operator/etc/crds/default/ \ --server-side \ --force-conflicts \ --validate=false
- APIGEE_NAMESPACE Namespace から
apigee-operator
リリースをクリーンアップして、ロールバック プロセスを完了します。helm uninstall operator -n APIGEE_NAMESPACE
clusterIssuer
などのクラスタ スコープのリソースは、operator
がアンインストールされると削除されます。次のコマンドを使用して再インストールします。helm upgrade operator apigee-operator/ \ --install \ --namespace apigee-system \ --atomic \ -f 1.12_OVERRIDES_FILE