[Qmonus SDK] パイプラインマイグレーション手順

1. QVS Configのマージ

※v2利用時に環境ごとのQVS Configを複数用意していない場合は本手順は不要です。

以下のコマンドを実行し、環境ごとに用意していたQVS Configをマージして1つのQVS Configを生成してください。ここでは、ステージングデプロイ済みのブランチ (通常main/master) で作業してください。ここで指定する値は以下の通りです。

v3_project_name: v3のプロジェクト名
v2_qvs_config_path: v2で利用しているQVS Config (旧AppConfig) のパスをマイグレーション対象分全てを指定

bash

valuestream-migration merge-qvsconfigs ${v3_project_name} \
  --microservice-name-v2 axis \
  --config ${v2_qvs_config_path01} \
  --config ${v2_qvs_config_path02}

コマンドを実行すると、QVS Configをマージし、その結果を .valuestream/config.yml に出力します。また、環境差分を解決し、パラメータ化が必要な値について、v3のDeployment Configの更新をします。登録を進めるか否かの選択肢が表示されるので、y を入力して前に進めてください。QVS Configの出力先を変更したい場合、--qvs-configオプションを利用ください。

例えば、以下のようにv2 QVS Configのstgとprodそれぞれで異なるsecurityGroup名をQVS Configで指定していた場合、そのドメイン名をパラメータ化し、Deployment Configに登録します。

yaml

# v2 QVS Config for stg
params:
  securityGroup: stg.security-group
---
# v2 QVS Config for prod
params:
  securityGroup: prod.security-group

---
# Merged v3 QVS Config
params:
  securityGroup: $(params.securityGroup)

---
# Qmonus Value Streamにパラメータ登録される値
---
# For Deployment `stg`
securityGroup: stg.security-group
---
# For Deployment `prod`
securityGroup: prod.security-group

WARNING

.solarray/stg/config.yml のように、v2 QVS Configのパス中に環境名（この例では stg ）が含まれている場合（v2の標準ルールに従っている場合）、マイグレーションツールがQVS Configの環境名を自動で解決します。このルールに従っていない場合、以下のようにカンマ区切りで環境名を指定してください。

bash

valuestream-migration merge-configs \
  --microservice-name-v2 axis \
  --config stg,foo/bar/config-stg.yml \
  --config prod,foo/bar/config-prod.yml

2. QVS Configのアップグレード

以下のコマンドを実行し、CI/CD設定をv2からv3に移行してください。ここで指定する値は以下の通りです。

v3_project_name: v3のプロジェクト名
migration_rule_name: マイグレーションルール名を以降に記載する表から選択して指定ください。
v3_qvs_config_path: 生成したv3 QVS Config
- マージ不要の場合、v2で利用していたQVS Configをそのまま指定ください
- 省略した場合、.valuestream/config.yml を利用します。
plugin_repo_name: Qmonus SDKのpluginを管理するリポジトリ名
- sample_plugins のように _plugins が付与された名前を指定ください。
config_repo_name: Qmonus SDKのconfigを管理するリポジトリ名
- sample_configs のように _configs が付与された名前を指定ください。

bash

valuestream-migration migrate-adapters ${v3_project_name} ${migration_rule_name} \
  --qvs-config ${v3_qvs_config_path} \
  --microservice-name-v2 axis \
  --inject-var pluginRepo=${plugin_repo_name} \
  --inject-var configRepo=${config_repo_name}

本コマンドを実行することで新しいQmonus SDK用Cloud Native Adapterを利用する .valuestream/config.new.yml を生成します。

指定するマイグレーションルール名は以下のとおりです。

migration_rule_name	説明
`qmonus-sdk-sdp`	Qmonus SDKをSSS-SDPアーキテクチャでかつプロジェクト専用のGKEで運用しているケース
`qmonus-sdk-kujira`	Qmonus SDKをSSS-SDPアーキテクチャでかつKUJIRA基盤で運用しているケース
`mvp`	Qmonus SDKをKUJIRA基盤で運用しているケース（MVP Project限定）
`common-axis-public`	Qmonus SDKを共通AXIS基盤で運用かつAPIを外部公開しているケース
`common-axis-private`	Qmonus SDKを共通AXIS基盤で運用かつAPIを外部公開していないケース

3. CI/CD設定の移行

以下のコマンドを実行し、CI/CD設定をv2からv3に移行してください。ここで指定する値は以下の通りです。

v3_project_name: v3のプロジェクト名
v3_qvs_config_path: 生成したv3 QVS Config

本コマンドは、QVS Config中のmoduleフィールドで宣言しているGit Repositoryをアクセストークンを使ってFetchします。対象のGit Repositoryにアクセス権限をもつアクセストークンを環境変数 GIT_TOKEN に予めセットして実行ください。このGIT_TOKENは、このコマンド実行時にのみ利用しますので、個人のトークンを利用いただいて大丈夫です。

bash

export GIT_TOKEN=${access_token}

valuestream-migration migrate-bluegreen-pipelines ${v3_project_name} \
  --qvs-config .valuestream/config.new.yml

WARNING

SSOが有効化されているリポジトリを利用する場合、アクセストークンがSSOにリンク済みであることを確認ください。v2利用者の多くの方が利用しているgithub.com/qmonusは、SSOを有効化しているため、トークンにSSOがリンク済みでない場合、コマンドが失敗します。

上記コマンド実行後、manifests-v3/${v3_project_name}にv3で利用するAssemblyLine/Pipeline/Taskが出力されます。Value StreamへのPipeline登録を進めるか否かの選択肢が表示されるので、y を入力して前に進めてください。CI/CDパイプラインとして通常利用いただくAssemblyLineに加えて、マイグレーション時にのみ利用するステート移行用のAssemblyLineが登録されます。

上記で出力されたAssemblyLine/Pipeline/Taskについては、今後のデバッグ、再現用にIaCとしてリポジトリにコミットいただくことを推奨します。

4. QVS ConfigのPush

生成されたQVS ConfigをGitリポジトリにCommitし、リモートリポジトリにPushしてください。ここで、Push先のブランチは v3-migration を指定ください。

bash

mv .valuestream/config.new.yml .valuestream/config.yml
git checkout -b v3-migration origin/main
git add .valuestream/config.yml
git commit -m 'v3 qvs config'
git push origin v3-migration

上記手順は.valuestream/config.ymlを指定していますが、QVS Configのマージ手順で.valuestream以外の出力先を指定した場合、そこで出力されたファイルをCommitしてください。

WARNING

.valuestream/config.yml以外のファイル名でQVS Configをコミットした場合、Qmonus Value Streamのコンソール画面のApplication設定より、QVS Config Pathの値も合わせて変更ください。

5. （環境ごとに実施）CI/CD Secretの登録

Qmonus Value StreamコンソールからCI/CDに利用するSecretを登録してください。Git Token、Google Cloud Service Account、Kubeconfig以外のSecretについては、事前にマイグレーション済みですが、これらのSecretについては再生成・登録いただきます。

Git Tokenの登録手順は以下のとおりです。

左メニューより、Repositoryを選択します。
マイグレーションツールによって生成済みのリポジトリを選択します。
画面右上のEDITボタンを押下します。
「Git Token」フォームにTokenの文字列を入力します。

Git Tokenについては、ご利用のアプリケーションリポジトリのCloneが可能な権限をもつPersonal Access Tokenを取得ください。個人のアカウントではなく、マシンアカウントの利用を推奨します。

Google Cloud Service Account、Kubeconfigの登録手順は以下のとおりです。

左メニューより、Applicationを選択します。
Deploymentsメニューに表示されるDeploymentのうち、Secret登録するDeployment名を選択します。
画面右上のEDITボタンを押下します。
「Credentials」フォームにGoogle Cloud Service AccountとKubeconfigの文字列を入力します。

Google Cloud Service Accountは、v2で利用していたService AccountもしくはCI/CDパイプラインの実行に必要な権限を付与したService Accountを新規作成してご利用ください。通常のQmonus SDKデプロイの場合、以下の権限が必要です。

GCRへの書き込み権限(roles/storage.legacyBucketWriter , roles/storage.objectViewer)
- Permissions and roles
- Cloud Storage に適用される IAM のロール
Redis Export権限 (roles/redis.viewer)
- Permissions and roles
SQL Export権限 (roles/cloudsql.viewer)
- Roles

Kubeconfigは、最新のqvsctlツールを利用して生成できます。利用しているKubernetesクラスタの運用者が他にいる場合は、必要な権限を持つKubeconfigを受領してください。 qvsctlツールを使ったKubeconfigの生成方法は以下のとおりです。Qmonus SDKのデプロイにはClusterリソースを作成するため、-pオプションの指定が必要です。詳しくはリファレンスを参照してください。

bash

kubectl config use-context ${context_of_your_cluster}
qvsctl plugin gen-kubeconfig -p -n qmonus-valuestream

6. （環境ごとに実施）Application Secretの登録

Qmonus Value StreamコンソールからQmonus SDKで利用するApplication Secretを登録してください。

左メニューより、AssemblyLineを選択します。
一覧からマイグレーションツールが生成したState移行用AssemblyLineを選択します。
- migrate-${app_name}-${deployment_name} という命名規則ですので、移行対象の環境のものを選択してください。
上記で選択したAssemblyLine名が画面中央に表示されるので、その名前を再度選択して詳細画面に遷移します。
詳細画面のPipelines (Stages) に表示されているstate-migrationカードを選択し、画面下部に表示されているSecretsフィールドを全て埋めます。

具体的なSecretの設定方法については、ガイドを参照してください。すでにv2利用時にSecretをGoogle Cloud Secret Managerに登録されているユーザは、Secret Managerに登録済みのSecretとアプリケーションに読み出すSecretを関連付けしてください。

7. （環境ごとに実施）State移行

DANGER

本手順は、アプリケーションPodの削除を伴う危険工程です。（一方で、本手順以前の作業はユーザ影響なく事前に実施可能です）

本工程で実行するAssemblyLineは、トランザクション有無を確認しません。作業中にトランザクションが開始し、かつ処理中のPodを削除した場合、そのトランザクションはエラーになりますのでご注意ください。

この手順で、v2を使ってデプロイしていたEXAMとQmonus SDKのInternal Endpoint (private IPのAPI Endpoint) を削除します。継続して利用が必要な方は対応手順についてサポートメンバまで問い合わせください。

以下のコマンドを実行し、v2からv3へStateを移行します。具体的には、state移行用のAssemblyLineを実行します。ここで指定する値は以下の通りです。

v2_project_id: v2のプロジェクト名
v3_project_name: v3のプロジェクト名
deployment_name: 移行する環境名

bash

valuestream-migration run-state-migration ${v2_project_id} ${v3_project_name} \
  --deployment-name ${deployment_name} \
  --microservice-name-v2 axis

Qmonus SDKのパイプラインのマイグレーションは、Qmonus Value Streamコンソールによる手動承認 (approve) が必要です。以下の手順にしたがって、危険工程を含む作業をサービス正常性を確認しながら承認してください。

左メニューより、AssemblyLineを選択します。
一覧からマイグレーションツールが生成したState移行用AssemblyLineを選択します。
- migrate-${app_name}-${deployment_name} という命名規則ですので、移行対象の環境のものを選択してください。
上記で選択したAssemblyLine名が画面中央に表示されるので、その名前を再度選択して詳細画面に遷移します。
HISTORYタブを選択し、実行中のAssemblyLineのDETAILボタンを押下します。
以下の図のようにApprove待ち処理になった際に、画面を操作して次の処理に進めます。

ここで、v2パイプラインで過去にデプロイしたQmonus SDK leader podとguest podをそれぞれ削除する工程の前にapprove処理を合計2回挟んでいます。Approve前にFrontal画面を開いてコンポーネント状態やトランザクションがないことを確認することを推奨します。

本コマンドの最後の処理で、v2 Workflowを無効化します。以降、v2を使ったアプリケーションのデプロイはできません。

本コマンドが途中で停止してしまったとしても、再度実行することで途中から処理を再開します。たとえば、AssemblyLine完了待ちの状態でクライアント端末のネットワークトラブルなどが原因でツールが異常終了してしまったとしても、再度コマンドを実行することで、完了待ちの状態から再開します。

v2でMulti-promote機能を利用されている場合、すなわちRelease Workflowを使ってデプロイ先Scopeを指定してデプロイしている場合、デプロイ対象の環境の数だけ、上記コマンドでState移行いただく必要があります。

事後対応

マイグレーション完了後、こちらのドキュメントを参照して、v3を実利用するために必要な準備をしてください。

[Qmonus SDK] パイプラインマイグレーション手順 ​

1. QVS Configのマージ ​

2. QVS Configのアップグレード ​

3. CI/CD設定の移行 ​

4. QVS ConfigのPush ​

5. （環境ごとに実施）CI/CD Secretの登録 ​

6. （環境ごとに実施）Application Secretの登録 ​

7. （環境ごとに実施）State移行 ​

事後対応 ​

[Qmonus SDK] パイプラインマイグレーション手順

1. QVS Configのマージ

2. QVS Configのアップグレード

3. CI/CD設定の移行

4. QVS ConfigのPush

5. （環境ごとに実施）CI/CD Secretの登録

6. （環境ごとに実施）Application Secretの登録

7. （環境ごとに実施）State移行

事後対応