このページでは、CI/CD ワークフローがインストールおよび構成された後に、Looker で CI/CD ワークフローを使用する方法について説明します。
この手順では、開発、QA、本番からなる 3 層システムを使用します。ただ、同じ原則は 2 層および 4 層のシステムにも適用できます。
またこの手順では、Git プロバイダとして GitHub を使用することを前提としています。他の Git プロバイダを使用して CI/CD ワークフローを作成できますが、プロバイダに合わせてこれらの手順を変更する場合は、専門知識が必要です。
ワークフローの概要
LookML デベロッパーはまず、開発ブランチ（通常は dev-my-user-ydnv のような名前）でコードを記述し、Spectacles で変更をテストし、コードを commit します。最後に、pull リクエストを開き、コードを main ブランチとマージします。
pull リクエストが開かれると、デベロッパーが GitHub に誘導されます。デベロッパーは、従来の commit スタイルでわかりやすい PR タイトルを作成し、変更履歴に含められる説明にコメントを追加する必要があります。Spectacles テストの結果は、PR にコメントとして追加する必要があります。
次に、デベロッパーは GitHub でレビュー担当者を選択する必要があります。レビュー担当者は通知を受け取り、レビューを PR に追加できるようになります。レビュー担当者が変更を承認すると、PR は main ブランチと統合されます。Webhook が呼び出され、開発環境に変更が反映されます。
自動的に Release Please 自動化が実行され、2 番目の PR が開き、新しいタグ付きのリリースが作成されます。または、この目的のためにすでに PR が開いている場合は、Release Please はその PR を更新します。リリース PR にはバージョン番号が関連付けられています。また、含まれる変更のタイトルと説明を含む変更履歴も含まれています。
Release Please が生成した PR が承認されてマージされると、新しいバージョンタグが生成され、変更履歴が main ブランチとマージされます。Looker の QA インスタンスと本番環境インスタンスは、高度なデプロイモードを使用してこのバージョンを選択できます。
リリースの番号付けと commit の命名に関するベスト プラクティス
リリースとそれに関連するタグには、使用している環境に合わせて、好きな形で名前や番号を付けることができます。ただし、ここではセマンティック バージョニングを使用しています。これは、Release Please プラグインと適切に連携するため、強く推奨されます。
セマンティック バージョニングでは、バージョンがピリオドで区切られた 3 つの数値で構成されます: MAJOR.MINOR.PATCH
PATCHは、リリースでバグが修正されるたびに増分されます。- リリースで、下位互換性を維持しつつ機能が追加または調整されるたびに、
MINORが増分され、PATCHが 0 に戻ります。 - 下位互換性がない機能が追加されると、
MAJORが増分され、MINORとPATCHの両方が 0 に設定されます。
従来の commit とは、エンドユーザーへの影響に基づいて commit に名前を付けるシステムです。必須ではありませんが、従来の commit 命名の使用は Release Please プラグインでも役立ちます。
従来の commit の命名では、各 commit メッセージの先頭にが変更の範囲を示すインジケーターが付加されます。
- バグの修正は、
fix: set proper currency symbol on sale_amt formatのようにfix:で示されます。 - 新しい機能は、
feat: added explore for sales by territoryのようにfeat:で示されます。 - 互換性を破る変更がある機能は、
feat!:で示されます（例:feat!: rewrote sales explore to use the new calendar view）。 - ドキュメントが更新されても、LookML が変更されない場合、commit メッセージは
doc:で始まります。
従来の commit が一貫して使用されている場合、次に使用されるセマンティック番号の決定は通常は簡単なものになります。commit ログが fix: と doc: の commit のみで構成されている場合は、PATCH の値を増分する必要があります。feat: commit がある場合は、MINOR を増分する必要があります。feat!: がある場合は、MAJOR を増分する必要があります。Release Release プラグインでは、CHANGELOG ファイルを生成して、リリースに自動的にタグ付けすることもできます。
高度なデプロイモードの使用
変更を行い、開発インスタンスで PR として送信すると、Release Please プラグインにより変更に v1.2.3 のようなバージョンタグが付けられます。Looker の高度なデプロイモードにより、これらのバージョンが QA インスタンスと本番環境インスタンスの Looker UI で利用できるようになります。
変更をデプロイするには、Looker IDE から Deployment Manager を選択します。
Deployment Manager の右上にある [commit を選択] リンクをクリックします。次に、デプロイするタグに関連付けられているその他メニューを選択し、[環境にデプロイする] を選択します。
デプロイに再度タグ付けする必要はないため、[Deploy without tagging] を選択して、[Deploy to Environment] ボタンを押します。
最後に、Deployment Manager を使用して本番環境に push します。
Spectacles の使用
各デベロッパーは、Spectacles を使用して、開発ブランチにいる間に変更を検証できます。Spectacles には 4 つの異なるバリデータがあります。
デベロッパーが pull リクエストを送信したら、これらのテストを実行して、結果を PR のコメントにコピーすることをおすすめします。
SQL バリデータ
SQL バリデータは各 Explore をテストし、LookML ビューで定義されたすべてのフィールドがデータベース内の実際の SQL 列または有効な SQL 式に対応していることを確認します。次に示すように、SQL バリデータが呼び出されます。
$ spectacles sql --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
次に例を示します。
$ spectacles sql --config-file config-dev.yaml \
--project thelook_cicd \
--explores thelook_cicd/users \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
=================== Testing 1/1 explores [concurrency = 10] ===================
✓ thelook_cicd.users passed
Completed SQL validation in 1 minute and 7 seconds.
LookML Validator
LookML Validator は、LookML の変更が有効で、構文エラーがないことを確認します。次のように呼び出されます。
$ spectacles lookml --config-file config-dev.yaml \
--project PROJECT_NAME \
--branch DEV_BRANCH_NAME
次に例を示します。
$ spectacles lookml --config-file config-dev.yaml \
--project thelook_cicd \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
============= Validating LookML in project thelook_cicd [warning] ==============
✗ thelook_cicd/business_pulse.dashboard.lookml failed
✗ thelook_cicd/thelook_cicd.model.lkml failed
================ thelook_cicd/business_pulse.dashboard.lookml:28 ===============
[Error] Unknown field "users.state" in explore "users" for field_filter.
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=28
================ thelook_cicd/business_pulse.dashboard.lookml:36 ===============
[Warning] Unknown field "users.state" (for explore "orders" in model
"thelook_cicd") referenced in dashboard element.
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=36
[Additional errors snipped]
Completed validation in 6 seconds.
Content Validator
Content Validator は、Look やユーザー定義ダッシュボード（UDD）などの保存済みコンテンツが、変更後も引き続き機能するかどうかをテストします。ジョブを高速化し、管理しやすい結果を提供するため、検証は、指定した Explore に基づくコンテンツに対してのみ行われます。Content Validator は次のように呼び出されます。
$ spectacles content --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
次に例を示します。
$ spectacles content --config-file config-dev.yaml \
--project thelook_cicd \
--explores thelook_cicd/users \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv
==================== Validating content based on 5 explores ====================
✗ thelook_cicd.users failed
================= test dashboard for spectacles [TheLook_CICD] =================
Tile 'test dashboard for spectacles' failed validation.
Error in thelook_cicd/users: Unknown field "users.state".
Dashboard: https://gcpl2318.cloud.looker.com/dashboards/223
========================= Business Pulse [TheLook_CICD] ========================
Filter 'State / Region' failed validation.
Error in thelook_cicd/users: Unknown field "users.state".
Dashboard: https://gcpl2318.cloud.looker.com/dashboards/190
Completed content validation in 27 seconds.
Assert Validation
Assert Validation は、LookML に追加したデータ アサーションをテストして、データが正しく読み取られるようにします。例えば、LookML でのデータテストは次のようになります。
test: historic_revenue_is_accurate {
explore_source: orders {
column: total_revenue { field: orders.total_revenue }
filters: [orders.created_date: "2019"]
}
assert: revenue_is_expected_value {
expression: ${orders.total_revenue} = 626000 ;;
}
}
Assert Validation は次のように呼び出されます。
$ spectacles assert --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
次に例を示します。
$ spectacles assert --config-file config-dev.yaml \
--project thelook_cicd \
--explores thelook_cicd/users \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv
==================== Running data tests based on 1 explore =====================
✗ thelook_cicd.users failed
================ thelook_cicd/users/california_users_is_accurate ===============
Unknown filter field "users.state" in lookml test "california_users_is_accurate"
declaration.
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55
================ thelook_cicd/users/california_users_is_accurate ===============
Invalid filter: users.state
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55
================ thelook_cicd/users/california_users_is_accurate ===============
Assertion "count_is_expected_value" failed: expression evaluated to "No".
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55
Completed data test validation in 14 seconds.
Look とダッシュボードのリンクの安定性
デフォルトでは、Look とダッシュボードには、Look またはダッシュボードの URL で使用される昇順の数値 ID が付与されます。ただし、システム間でこれらの同期を維持する方法はありません。したがって、開発中の特定のダッシュボードの URL が、QA や本番環境の同じダッシュボードを参照することはありません。
UDD の場合、URL の一部として ID の代わりにスラッグを使用するオプションがあります。スラッグは、数値ではなく半ランダムな文字セットです。スラッグはインポートの一部として設定でき、開発、QA、本番環境での同じ UDD を類似の URL で参照できます。ベスト プラクティスとして、ID の代わりにスラッグを使用することをおすすめします。UDD に Look や他の UDD から「クリックスルー」する場合には特に推奨されます。
スラッグは、gzr dashboard cat の出力を調べることで確認できます。スラッグは、ダッシュボード URL で数値 ID の代わりに使用できます。
Gazer を使用したユーザー コンテンツの移行
開発、QA、本番環境の間で Look やダッシュボードなどのコンテンツをコピーすることが役立つ場合が多くあります。新しい LookML の追加を紹介するコンテンツを作成したり、LookML の変更後も保存されたコンテンツが引き続き正しく機能するようにしたりできます。このような場合は、Gazer を使用してインスタンス間でコンテンツをコピーできます。
LookML ダッシュボード
LookML ダッシュボードは、通常の LookML CI/CD ワークフロー中にインスタンス間で同期されます。ただし、UDD が LookML ダッシュボードと同期されている場合は、次のコマンドを使用して Gazer で更新できます。
gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL
ユーザー定義のダッシュボード
ユーザー定義ダッシュボード（UDD）は、ダッシュボードの ID と、UDD が存在する Looker インスタンスの URL を参照することで、Gazer で移行できます。Gazer は、ダッシュボード構成を JSON ファイルに保存し、ターゲットの Looker インスタンスにインポートします。
UDD 構成を抽出するコマンドは次のとおりです。
gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .
これにより、ダッシュボードの構成を含む Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json という名前のファイルが生成されます。
次のコマンドを使用して、UDD をターゲット システムにインポートできます。
gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL
Looks
Look の移行は、UDD の移行と非常によく似ています。まず、Gazer を使用して Look 構成を JSON ファイルに保存します。
gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .
次に、Look をターゲット インスタンスにインポートします。
gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL