Qmonus SDKマイグレーションガイド(2022/4)

2022/4月のQmonusのサービス化に伴い、今後もSDKを継続利用いただく際には、正式提供版へのマイグレーションが必要です。ここではSDKのマイグレーションに伴う作業について記します。

現在利用のSDKバージョンは、2022年9月末を目処にサポートを終了する予定です。

Qmonus SDK のv22.2へのマイグレーションの前に、Qmonus SDK Lab (v3) へのマイグレを実施してください。現在ご利用のLab [ Qmonus Lab (v1)/ SDK Lab (v2) ]とは別のシステムでアーキテークチャーも異なるため、現在ご利用の開発環境を引き続き利用することはできません。新たにLab v3から作成した環境をご利用いただく必要があります。

Qmonus SDK Lab v3 : https://console.sdk-lab.qmonus.net
マニュアル : https://docs.sdk-lab.qmonus.net/

既存のLab(v1/v2) については、2022年5月末を目処に提供終了を予定しています。

ここまでの流れを図解します。

マイグレーションの流れ

Labのマイグレーション

現在利用中の状態

SDK Lab v3 にログインし、開発用GCPのプロジェクト情報を登録します。

SDK Lab v3のログインには利用申請が必要です。

SDK Lab v3 にログインし、SDKバージョンを指定して新しく開発環境を作成します。

事前に利用するSDKバージョンをお知らせください。

新しい環境での動作確認を実施し問題がなければ、既存のLabから開発環境を削除します。

マイグレーションが完了しました。

ここまでを2022/5月末までに実施してください。

SDKのマイグレーション

SDK Lab v3 から開発環境のフレームワークバージョンを v22.2 に更新します。

ここまでを2022/9月末までに実施してください。

お願い事項

商用環境の v22.2LTS へのマイグレが完了後に、サポートまで連絡をお願いします。（当該バージョンの削除を行います。）

1. SDK Labのマイグレーション手順

1-1. 事前準備

Lab v3へのログインアカウントの申請

Lab v3へログインするためのアカウント申請が必要になります。各プロジェクトの管理者アカウントの申請を行なってください。開発者アカウントの作成に関しては、管理者にて実施してください。

申請先　Slack チャネル（ @qmonus-ask）での申請

※ slackでのサポート連絡ができない場合はメールでも可 [ ****qmonus-support@ntt.com ]

**

申請内容

・希望するプロジェクト名（Lab / ValueStream のポータルに表示されます）

・プロジェクトの詳細

・管理者メールアドレス【複数可】

※ 個人のメールアドレスで、利用可能なメールアドレス（inviteメール通知用）

・ご利用のGCPのサービスアカウント

※ SDKのコンテナイメージのPullを許可するために必要、既存利用の場合は不要

・利用するSDKバージョン（SDK / Portal / ApiFront それぞれPATCHを含む形式で）

・商用利用中のSDKバージョン（SDK / Portal / ApiFront それぞれPATCHを含む形式で）

・商用利用中のミドルウエアバージョン（redis / mysql or postgres それぞれ）

SDK Lab (v3) では、提供するSDKコアバージョンを限定しています。（デフォルトは v22.2LTS ）
SDK Labのマイグレの際はSDK Lab(v3)で現在ご利用のSDKバージョンを継続利用するための設定が必要になりますので、サポートまでお知らせください。

開発環境のGKEバージョンアップ

GKEのバージョンを v1.21 に更新してください。

2022/4/1 時点では、GKEバージョンについては、v1.21 を推奨しています。**v1.22以降はサポートしていません。**特別な要件がない限りは推奨バージョンのご利用をお願いします。次回リリースにて、v1.22以降もサポート予定です。

1-2. マイグレの注意点

Lab v2からの変更点

・ポータルの操作方法が異なりますが、基本的な利用方法については大きな差分はありません

・Lab v2同様に開発環境作成前にクラウド情報 / リポジトリ情報が必要です。

※ v2で登録した内容は引き継げませんので、再度v3から登録をお願いします。

Lab v1からの変更点

・開発環境作成に関する利用方法が変更されています。特にCasval(ApiFront)の利用方法については大きく変更されています。

・お使いのクラウド/リポジトリの設定をユーザ自身で登録する必要があります。

※ 詳細手順に関してはドキュメントを参考してください。

https://docs.sdk-lab.qmonus.net/guide-v3/guide4.html

1-2. Labの設定

開発環境作成の前に、SDK Lab v3 へ利用するクラウドやリポジトリの情報を登録します。

開発環境デプロイ先のクラウドの設定

https://docs.sdk-lab.qmonus.net/guide-v3/guide4.html#クラウドサービス設定の入力

GITアクセス用の設定（マシンユーザ）

https://docs.sdk-lab.qmonus.net/guide-v3/guide4.html#リポジトリサービス設定の入力

ntt.comユーザでtamac.ioを利用している場合は、GitHubのシート数削減のため、Lab v3共通で利用するGit設定を設定しておきます。

任意のグループの作成

https://docs.sdk-lab.qmonus.net/guide-v3/guide4.html#グループの作成

現状、グループは開発環境をグループ化する程度の機能しかありませんが、環境作成に必要な情報なので、必ず１つは作成してください。

1-3. Labから開発環境を作成する

https://docs.sdk-lab.qmonus.net/guide-v3/guide5.html

https://docs.sdk-lab.qmonus.net/guide-v3/guide6.html

注意：SDK Portalの設定値の変更

Lab v3 で、v22.2 以前のバージョンの SDK Portalを起動する場合は、settings.arguments のJSONフィールドの値に加えて、以下のような設定を追加してください。
jsx
"+config_dir" : "/var/plugins/${プラグインディレクトリ名}/${frontalディレクトリ名}",
SDKポータルの外部コンフィグをコンフィグファイルに保存している場合は、settings.configPath で以下のようにコンフィグファイルを明示的に指定してください。
jsx
xxx_configs/frontal/development/config.yml

2. フレームワークマイグレーション手順

2-1. Lab推奨ディレクトリ構成への変更

SDK Lab v3でのデプロイを簡易化するため、QmonusSDKプラグイン資材のディレクトリ構成を以下を推奨参考に見直してください。

特に、SDKポータルの資材(/frontal以下)関しては、v22.2 で大きく仕様が変わっているので、カスタムダッシュボードや、サービスポータルなどSDKポータルの機能をご利用のプロダクトは注意してください。（2-4 項で詳細記載）

SDK Lab v3 では環境作成時に利用するGitリポジトリを複数指定することができます。またそれぞれのリポジトリの用途（種類）を指定することで、それぞれのマイクロサービスへの設定を自動化することができます。

Qmonus-SDK Plugins

QmonusSDKで開発するアプリケーションの資材です。構造は配下が推奨になります。

jsx
/hogehoge_plugins　　　　　　　  ## 命名規則はありません
  |
  |- /axis                     ## SDK Core プラグイン資材
  |   |- ...
  |
  |- /frontal                  ## SDK Portal プラグイン資材
  |   |    |- /dashboards           ## カスタムダッシュボード
  |   |　　　　　　|- xx.yml          ## 直下に資材ファイルを配置
  |   |
  |   |- /widgets              ## ビルトイン Widget
  |   |- /api                  ## ビルトイン Api
  |   |- portal.json           ## ビルトイン Portal設定ファイル
  |   |- api.json　　　　　　　　 ## ビルトイン API設定ファイル
  |
  |- /netfaker
  |- /exam
  |
  |- requirements.txt          ## pipのパッケージリスト。
  |- init.sh                   ##

※ requirements.txt の修正によって、SDKプラグイン開発で利用するpythonライブラリを指定できますが、SDKコアの動作へ影響する場合があります。カスタマイズは自己責任で実施してください。

Qmonus-SDK Configs

SDK Lab v1で利用していた環境依存情報を格納する資材も、引き続き利用可能です。

jsx
/hogehoge_configs　　　　　　　　　　　　　　　　　　　　　　　　　　　　## 命名規則はありません
  |
  |- /axis                     ## SDK Core プラグイン資材
  |- /frontal                  ## SDK Portal プラグイン資材

Qmonus-SDK Configs / Qmonus-SDK Plugins の違い

Qmonus-SDK Plugins で指定した資材のディレクトリのみ、シェルコマンド(init.sh) や pipのパッケージリスト(requirements.txt) の参照が行われます。netfaker、examへの読み込みはPluginsに指定したディレクトリから実施されます。

Qmonus-SDK Plugins は１つの環境に１のみ設定が可能です。

Qmonus-ApiFront Plguins

ApiFrontでデプロイするプラグイン(spa)資材です。構造は配下が推奨になります。

jsx
/hogehoge_gui                  ## 命名規則はありません
   |- /client
   |     |- /dist              ## SPA ビルドファイル資材
   |          |- index.html    ## SPA indexファイル
   |- /e2e_test                ## E2E_Tester用シナリオファイル
   |- /plugins                 ## SSS連携用資材等
   |- config_dev.yml
   |- config_stag.yml
   |- config_prod.yml

2-2. SDKプラグインコードのマイグレ

SDKのアプリケーションの既存コードに一部修正が必要な場合があります。

以下のリリースノートとマイグレーション手順に従い、必要に応じて修正を行います。

リリースノート
- https://docs.sdk.qmonus.net/release/v22.2LTS/

マイグレーション手順（随時追加予定）

v21.2LTSシリーズからv22.2LTSに移行するには以下の修正が必要

SqlAlchemy 1.4化に伴うコード修正

SqlAlchemy 1.4対応おける既知の修正必須箇所

where in 句の修正が必要 (※ ただし、SQL.run()を使っている場合は除きます)

コード例

python
async with model.aiodb() as conn:
    cmd = model.Cell.update().\
          where(model.Cell.c.id.in_(updated_cell_ids)).\
          values({model.Cell.c.configVersion: cell_group.configVersion})
    await conn.execute(cmd)

エラー内容
ProgrammingError:(1064, "You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '[POSTCOMPILE_id_1])' at line 1")

コード修正例 (暫定)

python
async with model.aiodb() as conn:
    cmd = model.Cell.update().\
          where(model.Cell.c.id.in_(updated_cell_ids)).\
          values({model.Cell.c.configVersion: cell_group.configVersion})
    compiled = cmd.compile(dialect=conn._dialect,
                           compile_kwargs={"literal_binds": True})
    await conn.execute(str(compiled))

コード修正例 (本格対応)
- https://github.com/aio-libs/aiomysql/issues/577 の修正内容に追従する

and_() , or_() 句に対するappend不可

コード例


if "name" in context.params:
    or_filter = or_()
    [or_filter.append(model.CellGroup.c.name == param) for param in context.params["name"]]
    queries.append(or_filter)

エラー内容

AttributeError:Neither 'BooleanClauseList' object nor 'Comparator' object has an attribute '_text_converter_role'

コード修正例


if "name" in context.params:
    or_filter = or_(*[model.CellGroup.c.name==param for param in context.params["name"]])
    queries.append(or_filter)

現在ご利用のバージョンによっては、上記以外の修正も必要になる場合もあります。うまく起動しない場合や動作に差分がある場合はサポートに確認してください。

2-3. SDKポータルプラグインコードのマイグレ

SDKポータルで動作するプラグイン（カスタムダッシュボード/ビルトインサービスポータル）を利用している場合は修正が必要になります。

リリースノート
- https://developer.qmonus.net/document/frontal/08_releasenote
マイグレーション内容
- プラグインのディレクトリ構造に変更があります。資材のディレクトリ名や階層を変更してください。
- 【カスタムダッシュボード】の保存フォーマットが yml になりました。過去のダッシュボード資産（.json /.dashbaard）に関しても引き続き利用は可能ですが、保存時に新たに.ymlファイルが出力されます。ymlファイル出力後に、古いファイルは削除してください。
- 【ビルトインサービスポータル（メニュー組み込みポータル）】プラグインのカスタムポータルで読み込むファイル形式の、.jade はサポートされなくなりました。 .pug で置き換えてください。

2-4. ApiFront設定の見直し

ApiFrontでデプロイするSPAのコードへの影響はありませんが、利用機能によっては一部デフォルト動作が変更されているので、動作を確認し必要に応じてコンフィグの設定を見直してください。

リリースノート
- https://developer.qmonus.net/document/frontal/08_releasenote
マイグレーション内容
- デフォルトでSecurityPolicy設定が有効化されているので、SPAから外部サイトのコンテンツ読み込みはできません。SPAで外部コンテンツの参照が必要な場合は、以下の設定で明示的にCecurityPolicyの設定を行い、読み込みを許可してください。WAFを経由した環境においては、CSPの設定を無効にすることもできます。
```
jsx
+content.securityPolicy="default-src 'self' ;script-src 'unsafe-eval' http://xxxxxxx; ..."
    or
+content.securityPolicy=null
```
- ApiFrontのコアイメージからpuppeteerが除外されています。/echo APIでPDF生成機能を利用している場合は、SDK Lab v3 でApiFront環境作成時に、以下のような指定でpuppeteerのインストールが必要になります。またDockerFileにも追加が必要です
```
jsx
buildSettings
  command :  npm install puppeteer && ..
```

2-5. Examコードマイグレーション

Qmonus SDK Lab v3 で Examをご利用の場合の注意点

Lab v1 での環境と、Lab v3 の環境構成が異なるため、Lab v3でExamコードを実行する際には、以下の点にご注意ください。

① common.cliのコマンドの記載内容変更

Examのcommon.cliコマンドCommand Arguementで、SSH接続先の設定を確認し、「localhost」が指定されている場合は、「ssh」へ修正してください。


{
  "commands": [
    "xxxxxxx"
  ],
  "host": "localhost",　<- "ssh" に変更
  "password": "xxx",
  "port": 22,
  "username": "xxx"
}

3 その他、注意点など

古いSDKバージョン利用時の注意点

v20.7LTS などのバージョンをSDK Lab v3 で利用する際には、注意が必要です。

SDK

古いSDKバージョンでは、SDK Labのデフォルト設定ではプラグインの起動がうまく動作しないケースが確認されています。
setupDir の見直しが必要なケースがあります。それでも起動しない場合は、plugin 指定の[*] 表記を、具体的に読み込みするプラグインディレクトリに指定するなどを実施してください。

SDK Portal

古いSDK Portalでは、環境作成画面から起動パラメータの指定ができません。資材リポジトリにyamlファイルを作成し、SDK Portalの設定の「configPath」欄のチェックボックスにチェックして、テキストフィールドで指定し読み込みさせるようにします。
また、yamlファイルで定義している「環境名」「APIキー」はSDKの設定値一致させる必要があるので、環境作成時のSDK設定で「settings.region」欄、「options」欄のJSONフィールドのsuser-api-keyを、yamlの情報を参考に設定してください。

上記でも動作しない場合には、GCPのPod状態を確認しマニフェストを直接修正して起動させるなどの対処が必要なケースもあります。

できるだけ新しいバージョンのご利用を推奨します。

SDK Lab v3 からApiFrontをデプロイする際の注意点

SDK Lab v3 からApiFrontをデプロイする際の起動設定のデフォルト値に「 +recommendedMode:true」 が設定されています。この設定を有効にした場合オススメ設定で動作しますが、「+authentication.transparentTokens:true 」で起動することにより、/session 応答内容が変化します。


SPA側で、/session で取得できるtokenを利用しているプロダクトでは、この「 +recommendedMode:true」の設定を削除してデプロイするようにしてください。

v22.7LTS