Apigee ハイブリッドを apigeectl から Helm に移行する

この移行ツールは、apigeectl ベースのハイブリッド クラスタを Helm ベースのハイブリッド クラスタに移行する支援をします。このツールは、クラスタ コンポーネントを実際に置換しません。べき等であり、同じクラスタで何回も実行でき、毎回コンポーネントと組織のサブセットを準備します。

すべての apigee コンポーネントを一度に移行できます。Helm のアップグレード オペレーションは、ツールの実行後にコンポーネント単位で行うことができます。

このツールで Helm 管理に移行したハイブリッド クラスタの管理については、Helm チャートでの Apigee ハイブリッドのインストールと管理をご覧ください。

前提条件

  • Helm バージョン v3.14.2 以降。
  • 動作中の Apigee ハイブリッド 1.13 がインストールされているクラスタを指す動作中の kubeconfig ファイル。
  • 移行するハイブリッド コンポーネントの Kubernetes リソースのメタデータとアノテーションを変更する権限。

スコープ

このツールは実行時に次のオプションをサポートします。

  • apigee リソースの Namespace のカスタマイズ。デフォルトの名前空間: apigee
  • 選択したハイブリッド コンポーネントのみの移行。デフォルト: すべてのコンポーネントが移行される
  • 単一組織の移行のみ
  • 単一の環境のみ移行
  • 単一の環境グループ（apigee-virtualhost）のみ移行
  • 組織、環境、環境グループ用の Helm リリース名のカスタマイズ。

制限事項

  • このツールでは、以下のハイブリッド コンポーネントの Helm リリース名のカスタマイズはサポートしていません: apigee-operator、apigee-datastore、apigee-redis、apigee-telemetry、apigee-ingress-manager
  • 組織、環境、環境グループの Helm リリース名に対して行われたインタラクティブなカスタマイズは、実行間で自動的に保持されません。一時ファイルを編集して、後の実行でオプションとして提供できます。

  • 環境と環境グループのフィルタリングは、名前のみで行われます。これにより、複数の環境と環境グループが複数組織クラスタで移行される場合があります。

    たとえば、組織 org1 と org2 を持つ複数組織クラスタでは、環境 prod が両方の組織に存在し、--env=prod のみが指定されている場合、両方の環境が移行されます。単一の環境のみを移行する場合は、組織フィルタ --org=org1 または --org=org2 も指定する必要があります。

使用状況

構文

apigee-helm-migration [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]

生成された Helm リリース名

クラスタにデプロイされるすべての Helm チャートはリリース名を持つ必要があります。それは名前空間内で一意である必要があります。Helm のリリース名には、チャート名に対する命名規則も制限もありません。移行ツールは、すべてのコンポーネントに一意の Helm リリース名を生成します。

グラフ 単一組織のクラスタ 複数組織のクラスタ
apigee-operator operator operator
apigee-datastore datastore datastore
apigee-telemetry telemetry telemetry
apigee-redis redis redis
apigee-ingress-manager ingress-manager ingress-manager
apigee-org ORG_NAME ORG_NAME
apigee-env ENV_NAME[-env[-n]](1) ORG_NAME-ENV_NAME[-env[-n]]（1）
apigee-virtualhost (envgroup) VH_NAME[-env-group[-n]]（1） ORG_NAME-VH_NAME[-env-group[-n]]（1）

(1) 生成された名前が別の生成された名前と競合する場合は、名前の末尾に -env または -env-group が付きます。それらがまだ競合している場合は、-1 または -2 … がさらに末尾に付加されます。

Helm リリース名のカスタマイズ

移行ツールによって、Helm リリース名をインタラクティブにカスタマイズできます。Helm リリース名を非対話形式でカスタマイズする場合:

  1. このツールを 1 回実行して最初のプロンプトで終了し、自動生成されたリリース名を含む一時ファイルを作成します。次のような行が表示されます。
    INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames

  2. このファイルを移動またはコピーして編集してください。この編集されたファイルは、移行ツールを実行した際に -f オプションで渡すことができます。自動生成されたリリース名は次のようになります。

    orgs:
  example-apigee-org:
    helmReleaseName: example-apigee-org
    envs:
      prod:
        helmReleaseName: prod
    envGroups:
      prod-envgroup:
        helmReleaseName: prod-envgroup

    組織、環境、または環境グループの Helm リリース名をカスタマイズするには、そのオブジェクトの helmReleaseName フィールドを編集します。たとえば、組織のリリース名を custom-org、環境のリリース名を custom-env、環境グループのリリース名を custom-group に変更すると、結果のファイルは次のようになります。

    orgs:
  example-apigee-org:
    helmReleaseName: custom-org
    envs:
      prod:
        helmReleaseName: custom-env
    envGroups:
      prod-envgroup:
        helmReleaseName: custom-group

カスタム Namespace の使用

Apigee ハイブリッド v1.13 以降は、単一の Kubernetes Namespace で実行されます。すべてのハイブリッド コンポーネントは、この Namespace で実行されます。apigee はデフォルト名です。これらのコンポーネントには、任意のカスタム Namespace を使用できます。

カスタム Namespace を使用する場合は、Helm 移行ツールの実行時に --apigee-namespace my_custom_namespace フラグで指定する必要があります。

また、オーバーライド ファイルに namespace: my_custom_namespace トップレベル プロパティを追加する必要もあります。

手順

  1. 移行ツールを見つけます。

    この移行ツールは、/tools/migration/ に apigeectl と一緒にパッケージ化されています。

  2. 次のいずれかのコマンドを使用して、圧縮ファイルを抽出します。

    • Mac: 
      tar -xzf apigee-helm-migration_1.0.2_mac_64.tar.gz
    • Linux:
      tar -xzf apigee-helm-migration_1.0.2_linux_64.tar.gz
    • Windows: 
      tar -xzf apigee-helm-migration_1.0.2_windows_64.zip
  3. 移行ツールを実行します。デフォルトのオプションが許容される場合は、引数なしでツールを実行し、生成された Helm リリース名が適切な場合にはプロンプトを承認するだけで十分です。いくつかのシナリオの例を以下に示します。

    • シンプルなインストール（デフォルトの kubeconfig（~/.kube/config）、デフォルトの apigee 名前空間、デフォルトの Helm リリース名を使用）。

      すべてではないにしても、ほとんどの場合、次のコマンドで十分です: installationsHelm のアップグレード オペレーションは、ツールの実行後にコンポーネント単位で実行できます。

      ./apigee-helm-migration
    • カスタム名前空間を使用してすべてのコンポーネントを移行。
      ./apigee-helm-migration --apigee-namespace my_custom_namespace

    • operator コンポーネントと datastore コンポーネントのみ移行。

      ./apigee-helm-migration --components operator,datastore

        INFO: 00:22:48 using kubeconfig file  /usr/local/google/home/example/.kube/config
  INFO: 00:22:48 namespace for apigee resources:
  INFO: 00:22:48 	 apigee
  INFO: 00:22:48 processing all organizations in cluster
  INFO: 00:22:48 Components to migrate:
  INFO: 00:22:48 	 operator,datastore
  INFO: 00:22:48 dry-run:
  INFO: 00:22:48 	 false
  Continue with patching apigee resources for Helm migration? [y/n]: y
  INFO: 00:22:52 Processing component:  operator
  INFO: 00:22:54 Processing component:  datastore
  INFO: 00:22:55 Migration successful!

    • 特定の kubeconfig ファイルを指定し、apigee 名前空間に異なる名前を指定。

      ./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace

    • すべてのコンポーネントを移行するが、単一組織のみ。

      ./apigee-helm-migration --org=some-test-org

    移行が成功した場合の出力例を次に示します。

    INFO: 21:32:55 using kubeconfig file  /usr/local/google/home/example/.kube/config
INFO: 21:32:55 namespace for apigee resources:
INFO: 21:32:55 	 apigee
INFO: 21:32:55 processing all organizations in cluster
INFO: 21:32:55 processing all components
INFO: 21:32:55 dry-run:
INFO: 21:32:55 	 false
INFO: 21:32:55 cluster Apigee information:
INFO: 21:32:55 Apigee Organizations found:
INFO: 21:32:56 	 example-hybrid-dev
INFO: 21:32:56 Apigee Environments found (org: env):
INFO: 21:32:56 	 example-hybrid-dev : prod
INFO: 21:32:56 Apigee EnvGroups(apigeerouteconfigs) found (org: envGroup):
INFO: 21:32:56 	 example-hybrid-dev : prod-envgroup
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
INFO: 21:32:56 Helm release names for Apigee orgs/envs/envgroups:
orgs:
example-hybrid-dev:
helmReleaseName: example-hybrid-dev
envs:
  prod:
    helmReleaseName: prod
envGroups:
  prod-envgroup:
    helmReleaseName: prod-envgroup
Make changes to the release names for Apigee orgs/env/envgroups? [y/n]: n
Continue with patching apigee resources for Helm migration? [y/n]: y
INFO: 21:32:59 Processing component:  operator
INFO: 21:33:01 Processing component:  datastore
INFO: 21:33:01 Processing component:  redis
INFO: 21:33:02 Processing component:  ingress-manager
INFO: 21:33:02 Processing component:  telemetry
INFO: 21:33:03 Processing component:  orgs
INFO: 21:33:05 Processing component:  envs
INFO: 21:33:06 Processing component:  env-groups
INFO: 21:33:07 Migration successful!

    発生する可能性のあるエラー:

    • リリース名のファイルの解析エラー: 渡されたリリース名ファイルを確認します。
    • リソースが見つからない: Apigee ハイブリッドが完全にインストールされ、apigee リソースにアクセスする権限があることを確認します。

構成プロパティの変更

オーバーライド ファイルに次の変更を加えます。

  • Helm で管理される Apigee ハイブリッドは、apigeeIngressGateway プロパティを使用してクラスタ内のすべての Apigee Ingress ゲートウェイを構成します。ingressGateways プロパティは、名前付きの個々の Ingress ゲートウェイの apigeeIngressGateway の設定をオーバーライドします。

    apigeeIngressGateway を参照

    • クラスタ内のすべての Ingress ゲートウェイにグローバルな ingressGateways プロパティを apigeeIngressGateway プロパティに変更します。オーバーライド ファイルには少なくとも以下を含める必要があります。
      apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"

      例:

      apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
    • ingressGateways.name を含めてください。Ingress ゲートウェイをインスタンス化する際に必要になります。次に例を示します。
      • ingressGateways:
  name: INGRESS_GATEWAY_NAME
  • Workload Identity を有効にするプロパティが変更されました。
    • gcp.workloadIdentityEnabled に代わり gcp.workloadIdentity.enabled になりました。
    • すべてのコンポーネントに単一のサービス アカウントを使用する場合は、gcp.workloadIdentity.gsa を使用して指定できます。次に例を示します。
      gcp:
  workloadIdentity:
    enabled: true
    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
    • コンポーネントごとに個別のサービス アカウント（ほとんどの本番環境インストールの標準）を使用する場合は、コンポーネントの gsa プロパティでサービス アカウントを指定します。次に例を示します。
      logger:
  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"

    gcp.workloadIdentity.enabled、gcp.federatedWorkloadIdentity.enabled、GKE で Workload Identity を有効にするまたは AKS と EKS で Workload Identity 連携を有効にするをご覧ください。

トラブルシューティング

ハイブリッド v1.12 リリースの Helm 移行ツールには、既知の問題があります。この問題が解決するまでは、Cassandra のバックアップと復元に追加の手順が必要です。

手順は次のようになります。

  • 移行ツールを実行する前または実行後
  • Helm チャートをインストールする前

回避策のパッチをインストールするには、次の手順を行います。

  1. 現在の kubeconfig が、移行するクラスタを参照していることを確認します。これらの手順は、任意のディレクトリから実行できます。
  2. 次の内容のファイルを migration-operator-patch.yaml という名前で作成します。
    # migration-operator-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: operator
    meta.helm.sh/release-namespace: APIGEE_NAMESPACE
  labels:
    app.kubernetes.io/managed-by: Helm
  3. 次の内容のファイルを migration-datastore-patch.yaml という名前で作成します。
    # migration-datastore-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: datastore
    meta.helm.sh/release-namespace: apigee
  labels:
    app.kubernetes.io/managed-by: Helm
  4. 次の kubectl コマンドを実行します。
    kubectl patch clusterrole apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrole apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrolebinding apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrolebinding apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
kubectl patch -n APIGEE_NAMESPACE cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE ServiceAccount apigee-cassandra-restore-sa --patch-file ./migration-datastore-patch.yaml
  5. 次のコマンドを使用して、パッチファイルをクリーンアップします。
    rm migration-operator-patch.yaml
rm migration-datastore-patch.yaml

次のステップ

Helm チャートでの Apigee ハイブリッドのインストールと管理の手順で、Apigee ハイブリッド Helm チャートのインストールを続けます。

-help の出力

./apigee-helm-migration --help

Usage of ./apigee-helm-migration:
  -apigee-namespace string
      namespace used for apigee resources (default "apigee")
  -components string
      CSV of components to migrate. If empty then all components are migrated. Valid values are: operator,datastore,redis,ingress-manager,telemetry,orgs,envs,env-groups
  -dry-run
      perform a dry-run
  -env string
      restrict migration to a singular supplied env. If empty then all envs detected in the cluster are migrated
  -env-group string
      restrict migration to a singular supplied envGroup. If empty then all envGroups detected in the cluster are migrated
  -kubeconfig string
      (optional) absolute path to the kubeconfig file (default "/usr/local/google/home/example/.kube/config")
  -org string
      restrict migration to a singular supplied org. If empty then all orgs detected in the cluster are migrated
  -v	Increased logging verbosity
  -y	don't prompt for confirmation or for configuration of Helm releases