Qmonus Value Stream Docs

Appearance

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

1. QVS Configのマージ ​

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

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

  • v3_project_name: v3のプロジェクト名
  • app_name: 移行するアプリケーション名
    • v2のコンソール/UIの左のメニューに表示されるService名です。
  • v2_qvs_config_path: v2で利用しているQVS Config (旧AppConfig) のパスをマイグレーション対象分全てを指定
bash
valuestream-migration merge-qvsconfigs ${v3_project_name} \
  --microservice-name-v2 ${app_name} \
  --config ${v2_qvs_config_path01} \
  --config ${v2_qvs_config_path02}

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

例えば、以下のように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 --config stg,foo/bar/config-stg.yml --config prod,foo/bar/config-prod.yml

2. CI/CD設定の移行 ​

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

  • v2_project_id: v2のプロジェクトID
  • v3_project_name: v3のプロジェクト名
  • app_name: 移行するアプリケーション名
    • v2のコンソール/UIの左のメニューに表示されるService名です。
  • v3_qvs_config_path: 生成したv3 QVS Config
    • マージ不要の場合、v2で利用していたQVS Configをそのまま指定ください
    • 省略した場合、.valuestream/config.yml を利用します。

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

bash
export GIT_TOKEN=${access_token}

valuestream-migration migrate-pipelines ${v2_project_id} ${v3_project_name} \
  --microservice-name-v2 ${app_name} \
  --qvs-config ${v3_qvs_config_path}

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としてリポジトリにコミットいただくことを推奨します。

3. QVS ConfigのPush ​

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

bash
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

手順1で、QVS Configのマージをスキップした場合でも、以降の手順ではv3-migrationブランチが必要となりますので、.valuestream/config.ymlにv3で利用するQVS Configをコピーし、リモートリポジトリのv3-migrationブランチにコミットしてください。

WARNING

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

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

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

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

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

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

v2でGit SSHを使った認証を利用していたユーザは、本手順でRepository typeをSSHに変更し、SSH Keyを登録してください。SSHを利用する場合のRepository URLは git@github.com:org/repositoryの形式で指定ください。

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

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

Google Cloud Service Accountは、v2で利用していたService AccountもしくはCI/CDパイプラインの実行に必要な権限を付与したService Accountを新規作成してご利用ください。通常、Buildステージで生成したDocker imageをGCRまたはGARにpushする権限が必要です。

具体的な権限について、以下を参考にしてください。

Kubeconfigは、最新のqvsctlツールを利用して生成できます。 利用しているKubernetesクラスタの運用者が他にいる場合は、必要な権限を持つKubeconfigを受領してください。

qvsctlツールを使ったKubeconfigの生成方法は以下のとおりです。詳しくはリファレンスを参照してください。Namespaceリソースなど、Cluster scopeのリソースを作成する場合、-p オプションの指定が必要です。

bash
kubectl config use-context ${context_of_your_cluster}
qvsctl plugin gen-kubeconfig -n ${kubernetes_namespace}

WARNING

ここで設定するのはCI/CD実行時に利用するSecretですが、Applicationが利用するSecretについても、Qmonus Value Stream経由で登録できます。ただし、利用にあたって、v3プラットフォームの仕様に準拠したQVS Configを用意いただく必要があり、本マイグレーション手順ではサポートしていません。 マイグレーション直後は、v2で利用していたApplication Secretを継続利用できますが、Application Secretを新規登録／編集される際は、直接Secret Backend (Google Cloud Secret Manger) を操作してください。

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

WARNING

本手順は、「Qmonus SDKパイプラインのマイグレーション手順」とは違い、ユーザ影響のない工程です。

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

  • v2_project_id: v2のプロジェクト名
  • v3_project_name: v3のプロジェクト名
  • app_name: 移行するアプリケーション名
    • v2のコンソール/UIの左のメニューに表示されるService名です。
  • deployment_name: 移行する環境名
bash
valuestream-migration run-state-migration ${v2_project_id} ${v3_project_name} \
  --deployment-name ${deployment_name} \
  --microservice-name-v2 ${app_name}

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

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

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

事後対応 ​

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