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

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

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

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

前提条件

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

スコープ

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

apigee リソースの Namespace のカスタマイズ。デフォルトの 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 チャートはリリース名を持つ必要があります。それは Namespace 内で一意である必要があります。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]]⁽¹⁾`	`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 回実行して最初のプロンプトで終了し、自動生成されたリリース名を含む一時ファイルを作成します。次のような行が表示されます。
```
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
```
このファイルを移動またはコピーして編集してください。この編集されたファイルは、移行ツールを実行した際に -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 トップレベルプロパティを追加する必要もあります。

手順

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

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

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

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

移行ツールを実行します。デフォルトのオプションが許容される場合は、引数なしでツールを実行し、生成された Helm リリース名が適切な場合にはプロンプトを承認するだけで十分です。いくつかのシナリオの例を以下に示します。

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

ほとんどのインストレーションの場合、次のコマンドで十分です: Helm のアップグレードオペレーションは、ツールの実行後にコンポーネント単位で実行できます。
```
./apigee-helm-migration
```
カスタム Namespace を使用してすべてのコンポーネントを移行。
```
./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 Namespace に異なる名前を指定。
```
./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 ゲートウェイをインスタンス化する際に必要になります。次に例を示します。
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 チャートをインストールする前

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

現在の kubeconfig が、移行するクラスタを参照していることを確認します。これらの手順は、任意のディレクトリから実行できます。

次の内容のファイルを 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

次の内容のファイルを 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

次の 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

注: not found エラーは無視して構いません。

次のコマンドを使用して、パッチファイルをクリーンアップします。
```
rm migration-operator-patch.yaml
rm migration-datastore-patch.yaml
```

次のステップ

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

重要: 移行されるクラスタに対する手順に沿う場合は、helm upgrade コマンドが失敗した場合にリソースが誤って削除されないように、Helm コマンドから ‑‑atomic フラグを省略する必要があります。

-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