KustomizeからHelmへ
前提条件
- Kubernetesのバージョンが v1.21 – 1.23。
- LinuxまたはmacOSクライアントホストにKubectlユーティリティがローカルにインストールされていること。以下のガイドはWindowsクライアントホストをサポートしていません。
- クライアントホストにHelm v3.8以上がインストールされている。
- クライアントホストにYqがインストールされている。
- Kubernetesクラスタがハードウェアリソースを含む一般的なCognigy.AIの前提条件を満たしている。
- Kustomizeインストール用のCognigyシークレット（MongoDBとRedisの接続文字列）のバックアップがKubernetesマニフェストの形で存在する。
- マルチレプリカの MongoDB Helm Chart が使用されている。Cognigy.AI Helm ChartはシングルレプリカのMongoDB（mongo-server）と互換性がありません。シングルレプリカからマルチレプリカに移行していない場合は、移行ガイドに従ってください。
- Cognigy.AI Kustomize のインストールは、Cognigy.AI Helm Chart と同じバージョンでなければなりません。
- Cognigy.AI Kustomizeのインストールはv4.38以上である必要があります。
- 移行開始前にすべてのPVC/PV（MongoDB、Redis-Persistent、flow-modules、flow-functions）の Snapshot/ Backupが作成されている。
移行チェックリスト
ここでは2つの移行シナリオが想定されます：
- 既存クラスタ内での移行。
cognigy-aiネームスペースのCognigy.AI Helm ChartとmongodbネームスペースのMongoDB Helm Chartを既存のKustomizeインストールと一緒にインストールします。このプロセスにより、既存のストレージの移行が大幅に簡素化されるため、こちらのシナリオを強く推奨します。 - 新しいクラスタへの移行。 Cognigy.AIとMongoDB Helm Chartsを新しいクラスタにインストールします。このシナリオは最初のシナリオよりも複雑です。既存のPVCの基礎となるストレージを新しいクラスタに再接続できるようにするか、新しいクラスタのスナップショットからデータをリストアする必要があります。
移行を開始する前に、以下の操作を行います：
- MongoDB、redis-persistent、flow-modules、関数など、すべてのPVCのバックアップ（スナップショット）がクラウドプロバイダに作成されていることを確認します。
- Kustomizeインストール用のCognigy secretsのバックアップがあることを確認します。
- Cognigy.AI Helm Chart 用の
values_prod.yaml値ファイルを準備します。現在の Kustomize インストールのすべての調整（パッチ）が values_prod.yaml ファイルに正しく移行されていることをご確認ください： ENV 変数、リソースリクエスト/制限、レプリカカウントなど。 - MongoDB データベースの名前の変更セクションのスクリプトを準備します、事前に必要なパスワードの値を入力してください。
移行の準備
このセクションでは、KustomizeからHelmへのCognigy.AIの移行準備手順について説明します。これらの手順は事前に実行することができ、Cognigy.AIのインストールを停止する必要はありません。
シークレット
移行中、Cognigy.AI 製品はデフォルトから別のネームスペースに移動します。このドキュメントでは、cognigy-aiをターゲットネームスペースとしています。任意のネームスペースに置き換えることもできますが、cognigy-aiネームスペースを使用することを強く推奨します。したがって、既存のシークレットを新しいネームスペースに移行し、移行したシークレットをHelmリリースに通知する必要があります。これを行うには、以下の手順を実行します：
1. 移行スクリプトはこのリポジトリにあります。リポジトリを複製し、現在のCognigy.AIバージョンにチェックアウトします：
git clone https://github.com/Cognigy/cognigy-ai-helm-chart.git
git checkout tags/<release>
cd scripts/kustomize-to-helm-migration-scripts2. 既存のシークレットのバックアップをsecretsフォルダに置きます。
3. secretsフォルダをkustomize-to-helm-migration-scriptsフォルダにコピーします。
4. スクリプトを実行する前に、secretsフォルダに既存のシークレットがすべて保存されていることを確認します。
5. スクリプトを実行すると、migration-secretsフォルダにHelmインストール用の新しいシークレットが生成されます：
pip3 install -r requirements.txt
python3 secret-migration.py -ns cognigy-ai6. シークレットを新しいcognigy-aiネームスペースに適用します：
kubectl create ns cognigy-ai
kubectl apply -f migration-secrets永続ボリューム
このサブセクションでは、AWS（efs-provisonerを使用したEBSおよびEFS）およびAZURE（AzureディスクおよびAzureファイル）の永続ボリュームの移行について説明します。Cognigy.AIが別のクラウドプロバイダにデプロイされている場合は、移行手順を適宜変更する必要があります。
このサブセクションでは、既存のクラスタ内での移行について説明します。新しいクラスタシナリオへの移行では、古いクラスタで作成した永続ボリュームのスナップショットからデータをリストアする必要があります。このプロセスはクラウドプロバイダの設定により大きく異なるため、2番目のケースについてはコマンドを提供しません。インフラストラクチャデータのバックアップとリストアのプロセスおよびクラウドプロバイダのドキュメントをご参照ください。
1. 既存のCognigy.AI PVC（flow-modules, functions, redis-persistent）のスナップショットを作成します。
2. 移行中のPVの損失を避けるため、上記の3つのPVCの基礎となるPVを保持するようにReclaim Policyを設定し、対応するPV名をメモしておきます：
# get the PV names for PVs attached to flow-modules`, `functions`, `redis-persistent` PVCs of Kustomize installation:
kubectl get pv
# patch the reclaim policy for PV, set <pv-name> to the NAME from the previous command, repeat for all 3 PVCs:
kubectl patch pv <pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
# check that reclaim policy has changed to Retain:
kubectl get pv3. PVのIDを取得し、メモしておきます：
kubectl get pv | grep -E 'redis-persistent|flow-modules|functions'
for i in $(kubectl get pv | grep -E 'redis-persistent|flow-modules|functions' | awk '{print $1}')
do
echo $i
done4.（AWSのみ）上記2つのPVの基礎となるVolumes（EFSファイル共有）のIDを取得し、メモします。以下の手順でこれらの ID を使用する必要があります：
## Get details of the PVs, set <pv-name> to the NAME of PV attached flow-modules, functions, and redis-persistent PVCs:
kubectl describe pv <pv-name>
## Example for `flow modules` and `functions` PVs on AWS:
Source:
Type: NFS (an NFS mount that lasts the lifetime of a pod)
Server: fs-000000000001a.efs.eu-central-1.amazonaws.com5. （AWSのみ）： (AWSのみ): Cognigy.AI Helm Chartのvalues_prod.yamlに、前のステップで取得したflow-modulesとfunctionsのボリュームのIDを設定します：
# Example for AWS:
efs:
flowModules:
id: "fs-000000000001a"
functions:
id: "fs-000000000001b"6. (AWSのみ）： 既存のクラスタシナリオ内の移行では、既存のflow-modulesとfunctionsのストレージクラスと関連するロールバインディングに注釈とラベルを追加します：
## annotate `flow-modules` and `functions` StorageClasses
kubectl annotate storageclass flow-modules meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label storageclass flow-modules app.kubernetes.io/managed-by=Helm
kubectl annotate storageclass functions meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label storageclass functions app.kubernetes.io/managed-by=Helm
## AWS only: annotate related ClusterRoleBindings
kubectl annotate clusterrolebindings efs-provisioner-flow-modules meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label clusterrolebindings efs-provisioner-flow-modules app.kubernetes.io/managed-by=Helm
kubectl annotate clusterrolebindings efs-provisioner-functions meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label clusterrolebindings efs-provisioner-functions app.kubernetes.io/managed-by=Helm7. KustomizeとHelmインストール用のPVCマニフェストのバックアップを保存します：
kubectl get pvc -n=default redis-persistent -o yaml > redis-persistent-pvc-kustomize.yaml
kubectl get pvc -n=default flow-modules -o yaml > flow-modules-pvc-kustomize.yaml
kubectl get pvc -n=default functions -o yaml > functions-pvc-kustomize.yaml8. 次のステップで変更されるPVCマニフェストの別のコピーを作成します：
kubectl get pvc -n=default redis-persistent -o yaml > redis-persistent-pvc.yaml
kubectl get pvc -n=default flow-modules -o yaml > flow-modules-pvc.yaml
kubectl get pvc -n=default functions -o yaml > functions-pvc.yaml9. PVCから不要なフィールドを削除します：
for i in redis-persistent-pvc flow-modules-pvc functions-pvc
do
yq -i 'del(.metadata.annotations, .metadata.finalizers, .metadata.labels, .metadata.creationTimestamp, .metadata.resourceVersion, .metadata.uid, .status)' $i.yaml
done10. ステップ8で保存したPVCマニフェストを、3つのPVCすべてについて以下の方法で編集します：
metadata.namespaceをcognigy-aiに変更します。metadata.annotationsの下にmeta.helm.sh/release-name: cognigy-aiとmeta.helm.sh/release-namespace: cognigy-aiを追加します。metadata.labelsにapp.kubernetes.io/managed-by: Helmを追加します。spec.volumeNameをステップ2の各PV名に変更します。
Traefik
Cognigy.AIのインストールにデフォルトで同梱されているTraefikリバースプロキシを使っている場合、以下のコマンドを実行する必要があります。サードパーティのリバースプロキシを使っている場合は、これらのコマンドを実行する必要はありません：
kubectl annotate clusterrole traefik meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label clusterrole traefik app.kubernetes.io/managed-by=Helm
kubectl annotate clusterrolebindings traefik meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label clusterrolebindings traefik app.kubernetes.io/managed-by=Helm
kubectl annotate ingressclass traefik meta.helm.sh/release-name=cognigy-ai meta.helm.sh/release-namespace=cognigy-ai
kubectl label ingressclass traefik app.kubernetes.io/managed-by=Helm移行
このセクションでは、KustomizeからHelmへのCognigy.AIの実際の移行について説明します。移行にはCognigy.AIのインストールの停止時間が必要です。少なくとも2時間のメンテナンスウィンドウを設けてください。
MongoDB データベースの名前の変更
1. 現在のインストールをスケールダウンします：
for i in $(kubectl get deployment --namespace default --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')
do
kubectl --namespace default scale --replicas=0 deployment $i
done2. データベースの名前を変更し、新しいユーザーを作成します。Cognigy.AI Helm Chartでは、service-analytics-collector-providerデータベースの名前をservice-analytics-collectorに、service-analytics-conversation-collector-providerデータベースの名前をservice-analytics-conversationに変更しています。データベースの名前を変更するには、以下のスクリプトを実行し、パスワードの値をあらかじめ入力しておきます（スクリプト内のコメントをご覧ください）。MongoDB Helm のルートユーザー名 (root または admin) を確認し、データベースの移行時に使用します。
kubectl exec -it -n mongodb mongodb-0 bash
# rename the service-analytics-collector-provider, set admin root password in <password>
mongodump -u <root_username> -p <password> --authenticationDatabase admin --host "mongodb-0.mongodb-headless.mongodb.svc.cluster.local:27017,mongodb-1.mongodb-headless.mongodb.svc.cluster.local:27017,mongodb-2.mongodb-headless.mongodb.svc.cluster.local:27017" --archive --db=service-analytics-collector-provider | mongorestore -u admin -p <password> --authenticationDatabase admin --archive --nsFrom='service-analytics-collector-provider.*' --nsTo='service-analytics-collector.*'
# rename the service-analytics-conversation-collector-provider, set admin root password in <password>
mongodump -u <root_username> -p <password> --authenticationDatabase admin --host "mongodb-0.mongodb-headless.mongodb.svc.cluster.local:27017,mongodb-1.mongodb-headless.mongodb.svc.cluster.local:27017,mongodb-2.mongodb-headless.mongodb.svc.cluster.local:27017" --archive --db=service-analytics-conversation-collector-provider | mongorestore -u admin -p <password> --authenticationDatabase admin --archive --nsFrom='service-analytics-conversation-collector-provider.*' --nsTo='service-analytics-conversation.*'
# Create service-analytics-collector user in service-analytics-collector db
# Get the existing password from `cognigy-service-analytics-collector-provider` secret and put it into <password-service-analytics-collector>:
mongo -u <root_username> -p $MONGODB_ROOT_PASSWORD --authenticationDatabase admin
use service-analytics-collector
db.createUser({
user: "service-analytics-collector",
pwd: "<password-service-analytics-collector>",
roles: [
{ role: "readWrite", db: "service-analytics-collector" }
]
});
# Create service-analytics-conversation user in service-analytics-conversation db
# Get the existing password from `cognigy-service-analytics-conversation-collector-provider` secret and put it into <password-service-analytics-conversation>:
use service-analytics-conversation
db.createUser({
user: "service-analytics-conversation",
pwd: "<password-service-analytics-conversation>",
roles: [
{ role: "readWrite", db: "service-analytics-conversation" }
]
});
exit
exitCognigy.AIの永続ボリュームの移行
1. Cognigy.AI Helmリリースのflow-modules、function、redis-persistentのPVCをKustomizeインストールの既存PVにアタッチします：
## delete dynamically provisioned PVCs for flow-modules, functions and redis-persistent during Kustomization deployment
kubectl delete pvc -n=default flow-modules
kubectl delete pvc -n=default functions
kubectl delete pvc -n=default redis-persistent
## verify that dynamic PVCs are removed and that PVs from Kustomize installation still exist
kubectl get pvc
kubectl get pvc -n=cognigy-ai
kubectl get pv
# edit PVs for `flow-modules`, `functions` and `redis-persistent` and remove `spec.claimRef:` section completely
kubectl patch pv <pv-name> -p '{"spec":{"claimRef": null}}'
# check that PVs status has changed from `Released` to `Available`
kubectl get pv2. [Prepare Persistent Volumes(永続ボリュームの準備)] セクションで変更した PVC マニフェストをデプロイします。
# apply modified PVCs to the cluster
kubectl apply -f redis-persistent-pvc.yaml
kubectl apply -f flow-modules-pvc.yaml
kubectl apply -f functions-pvc.yaml
# check that status of PVs and PVCs has changed to Bound:
kubectl get pv
kubectl get pvc -n=cognigy-aiKustomizeからHelmへのCognigy.AIの移行
Cognigy.AIの移行は以下の手順で行います：
1. Cognigy.AI Helmリリースのデプロイメントを戻します：
helm registry login cognigy.azurecr.io \
--username <your-username> \
--password <your-password>
helm upgrade --install --namespace cognigy-ai cognigy-ai oci://cognigy.azurecr.io/helm/cognigy.ai --version HELM_CHART_VERSION --values values_prod.yaml2. すべてのデプロイが準備完了状態であることを確認します：
kubectl get deployments -n=cognigy-ai3.（リバースプロキシとしての Traefik のみ）LoadBalancer タイプの traefikサービスの EXTERNAL-IPが変更された場合、DNS レコードを traefikサービスの新しいEXTERNAL-IPを指すように更新します。Traefik IngressをAWS Classic Load Balancerで使用している場合は、DNSエントリのCNAMEを新しいEXTERNAL-IPに変更してください。新しい外部IP/CNAMEレコードを以下で確認してください：
kubectl get service -n=cognigy-ai traefikロールバック
Cognigy.AI Helmリリースが正しく機能せず、ロールバックが必要な場合は、以下の手順で行います：
1. Cognigy.AI Helmリリースのデプロイメントをスケールダウンします。
for i in $(kubectl get deployment --namespace cognigy-ai --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')
do
kubectl --namespace cognigy-ai scale --replicas=0 deployment $i
done2. Helmリリース用のPVCを削除します：
kubectl delete pvc -n=cognigy-ai flow-modules
kubectl delete pvc -n=cognigy-ai functions
kubectl delete pvc -n=cognigy-ai redis-persistent 3. Kustomizeインストール用のPVCをリストアします：
kubectl apply -f redis-persistent-pvc-kustomize.yaml
kubectl apply -f flow-modules-pvc-kustomize.yaml
kubectl apply -f functions-pvc-kustomize.yaml4. Kustomizeインストールを戻します：
cd kubernetes/core/<environment>/product
kubectl apply -k ./5. Cognigy.AI Kustomizeインストールが稼働したら、cognigy-aiネームスペース（Helmリリースのネームスペース）を完全に削除することで、Helmリリースをクリーンアップすることができます：
kubectl delete namespace cognigy-aiクリーンアップ
Cognigy.AI Helm リリースが正常に稼働した後、Kustomize インストールをクリーンアップすることができます：
1. MongoDBの古いデータベースを削除します（MongoDB Helm Chartのvalues_prod.yamlに従ってMONGODB_ROOT_USERをrootまたはadminに設定）：
kubectl exec -it -n mongodb mongodb-0 -- bash
mongo -u $MONGODB_ROOT_USER -p $MONGODB_ROOT_PASSWORD --authenticationDatabase admin
# Drop service-analytics-collector-provider
use service-analytics-collector-provider
db.dropDatabase()
# Drop service-analytics-conversation-collector-provider
use service-analytics-conversation-collector-provider
db.dropDatabase()2. デフォルトのネームスペースで実行されている Kustomize デプロイメントを削除します：
for i in $(kubectl get deployment --namespace default --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')
do
kubectl --namespace default delete deployment $i
done3. デフォルトのネームスペースにあるサービスを削除します：
for i in $(kubectl get service --namespace default --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}' | grep service-)
do
kubectl --namespace default delete service $i
done
# delete rabbitmq, redis, redis-persistent, and traefik
kubectl --namespace default delete svc rabbitmq redis redis-persistent traefikkubernetesサービスを削除しないように注意してください。
4. デフォルトのネームスペースにあるイングレスを削除します：
for i in $(kubectl get ingress --namespace default --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')
do
kubectl delete ingress $i --namespace default
done5. デフォルトのネームスペースからPVCを削除します（まだ存在する場合）：
kubectl delete pvc -n=default flow-modules
kubectl delete pvc -n=default functions
kubectl delete pvc -n=default redis-persistent6. (オプション) シングルレプリカからマルチレプリカにMongoDBを移行する場合、シングルレプリカのMongoDBセットアップのPVCを削除します：
kubectl delete pvc mongodb -n default