はじめに
先日の登壇で紹介した、fabric-cicd を使用した Microsoft Fabric ワークスペースの CI/CD チュートリアルを作成しました。
fabric-cicd を利用することで、Fabric ワークスペースのアイテムを単にコピーするだけでなく、環境差分を吸収しながら、Azure DevOps や GitHub のワークフローに組み込んでデプロイできます。
特に、次の3点が大きなメリットです。
-
柔軟なパラメーター設定による環境差分の吸収
開発環境と本番環境で異なるワークスペース ID、Lakehouse ID、接続先などを、デプロイ時に置き換えることができます。Fabric の配置パイプラインにおける配置ルールや Variable Library だけでは対応しづらい環境依存値もカバーできます。 -
Azure DevOps などを利用したワークフロー管理
Pipeline、Environment、承認フロー、変数グループなどを組み合わせることで、デプロイ手順を管理しやすくなります。 -
プログラムベースのデプロイによる拡張性
Python スクリプトとしてデプロイ処理を実装できるため、標準機能だけでは対応しづらい処理も柔軟に組み込めます。
この記事では、開発用の Fabric ワークスペースで作成した Notebook、Lakehouse、Variable Library、Semantic Model、Report などのアイテムを、Azure DevOps Pipeline から本番用ワークスペースへデプロイする流れをハンズオン形式で紹介します。
使用するサンプルリポジトリはこちらです。
発表内容：
この記事でやること
このハンズオンでは、次の流れを実施します。
- Azure DevOps Repos にサンプルリポジトリをインポートする
- 開発用ワークスペースでの開発（Notebook、Lakehouse、Semantic Model、Report）
- Azure DevOps Pipeline から本番用ワークスペースへデプロイする
-
parameter.ymlを使用して、環境依存の ID や OneLake URL を本番用に置き換える - 再デプロイし、本番用ワークスペースで Notebook と Report が動作することを確認する
構成イメージ
今回の構成は次のようになります。
Azure DevOps Repos
└── workspaces/<workspace name>/src
├── Notebook
├── Lakehouse
├── Variable Library
├── Semantic Model
└── Report
│
│ Git 統合
▼
Fabric workspace: DEV
│
│ Azure DevOps Pipeline + fabric-cicd
▼
Fabric workspace: PROD
開発用ワークスペースは Fabric の Git 統合で Azure DevOps Repos と同期します。
一方、本番用ワークスペースは Git 統合ではなく、Azure DevOps Pipeline から fabric-cicd を実行してデプロイします。
事前準備
このチュートリアルでは、次の環境が必要です。
| 項目 | 用途 |
|---|---|
| Azure DevOps | Repos と Pipeline を使用します |
| Azure サブスクリプション | Azure DevOps のサービス接続を作成するために使用します |
| Microsoft Fabric 環境 | 開発用・本番用ワークスペースを作成します |
| Fabric 管理者によるテナント設定 | サービスプリンシパルや Git 統合に必要な設定を有効化します |
Fabric テナント設定
Fabric 管理ポータルで、少なくとも次の設定を確認します。
-
サービスプリンシパルが Fabric API にアクセスできるようにする
-
Azure DevOps Git 統合で必要な場合、外部リージョンへの Git エクスポートを許可する
特に、Azure DevOps のリポジトリと Fabric テナントのリージョンが異なる場合は、Git へのエクスポートに関するクロスリージョン設定が必要になります（Azure DevOps には Japan East リージョンがないため）
サンプルリポジトリの構成
今回使用するテンプレートリポジトリは、次のような構成になっています。
.
├── .azuredevops/
│ ├── pipelines/
│ │ ├── deploy-ws-holws-prod.yml
│ │ └── templates/
│ │ └── jobs/
│ │ └── deploy-fabric-workspace.yml
│ └── variable-groups/
│ └── workspace-deploy/
│ └── template.vars
├── .deploy/
│ └── scripts/
│ └── deploy_fabric_workspace.py
└── workspaces/
├── template_parameter.yml
└── <workspace_name>/
└── src/
├── parameter.yml
├── Development/
├── Environment/
└── Storage/
主なファイルは次のとおりです。
| パス | 説明 |
|---|---|
.azuredevops/pipelines/deploy-ws-<workspace name>-prod.yml |
対象のワークスペースを PROD 環境へデプロイする Pipeline 定義です。workspace nameを今回はhol_ws としています |
.azuredevops/pipelines/templates/jobs/deploy-fabric-workspace.yml |
Fabric ワークスペースをデプロイする共通ジョブテンプレートです |
.azuredevops/variable-groups/workspace-deploy/template.vars |
Azure DevOps の変数グループに登録する値のテンプレートです |
.deploy/scripts/deploy_fabric_workspace.py |
Pipelineから呼び出されるFabricワークスペースデプロイスクリプトです。fabric-cicdを使って、リポジトリ内のFabricアイテム定義を指定ワークスペースへ反映します。 |
workspaces/template_parameter.yml |
デプロイ時に環境依存値を置き換えるための parameter.yml テンプレートです |
workspaces/<workspace name>/src |
Fabric ワークスペースからエクスポートされたアイテム定義を格納するディレクトリです。 workspace nameを今回はhol_ws としています |
1. Azure DevOps を準備する
Repos セットアップ
まず、Azure DevOps の Repos にサンプルリポジトリをインポートします。
-
Azure DevOps の対象プロジェクトを開き、Repos の Import repository から、次の GitHub リポジトリをインポートします。
チュートリアル用のrepoを使用します。
https://github.com/ryoma-nagata/fabric-cicd-template.git
-
インポート後、必要に応じてワークスペース用フォルダ名を変更します。
既定では次のパスになっています。hol_wsのままでも問題ありません。workspaces/hol_ws/src
Azure サービス接続の作成
次に、Azure DevOps Pipeline から認証するためのサービス接続を作成します。
-
Azure DevOps の対象プロジェクトで、Project settingsからService connectionsを開きます。
-
Azure Resource Manager のサービス接続を作成します。
作成したサービス接続名は、後で Pipeline の YAML で使用します。
既定値：
azure_service_connection_name: 'azure-service-connection'指定したリソースグループに権限付与されます（サービスプリンシパルがAzureへのサインイン時に必要となりますが、このデプロイでは使用しません。）
このサービス接続で使用されるサービスプリンシパルがデプロイを行います。名前を変更したい場合は、以下から変更します。
参考：
- https://learn.microsoft.com/ja-jp/azure/devops/pipelines/release/configure-workload-identity?view=azure-devops&tabs=app-registration
- https://learn.microsoft.com/ja-jp/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-app-registration-with-workload-identity-federation-automatic
2. 開発用 Fabric ワークスペースを作成する
セットアップ
-
Fabric ポータルで、開発用のワークスペースを作成します。
-
作成後、ワークスペース設定から Git 統合を構成します。
必ず、repos上のsrcフォルダを Gitフォルダ―として設定します。
workspaces/hol_ws/src
-
接続後、Git からワークスペースへ同期します。
同期が完了すると、開発用ワークスペースにサンプルのアイテムが表示されます。
名前 説明 LH_CICD サンプルテーブルを構成するレイクハウスおよびSQL分析エンドポイント MLVs マテリアライズドレイクビューの設定とサンプルデータ投入のノートブック VL_Main ワークスペースごとに異なる値を扱うための変数ライブラリ
[任意]feature ブランチワークスペースの作成
ブランチの運用方法にもよりますが、開発者や機能ごとにブランチおよびワークスペースを作成し、開発を行い、main に統合をしていきます。
なお、ブランチワークスペースの作成は必須ではありません。単純な検証であれば DEV ワークスペース上で直接作業しても構いません。
参考：https://learn.microsoft.com/ja-jp/fabric/cicd/git-integration/branched-workspace
-
ソース管理からワークスペースに分岐を選択
-
ブランチワークスペースを作成
-
ブランチがDevOps 上に作成され、ワークスペースと同期されます
ここから開発を進めます
ノートブックの開発
このサンプルでは、Notebook 内で Variable Library の値を参照し投入するデータの内容を変更しています。
例えば、環境名を表す ENV_NAME を Variable Library から取得することで、DEV / PROD などの環境差分を管理できます。
-
ノートブックを開きます。LH_CICDを既定のレイクハウスとして紐づけます
分岐により作成したワークスペース上のレイクハウスを選ぶと、開発ワークスペース上のレイクハウスにはデータは反映されません。
担当者間で同じデータストアを参照するか、専用のデータストアを使用するのか、適宜使い分けてください。
専用のデータストアで作業を行った場合は、ブランチの統合後に、既定のレイクハウスの紐づけ先の調整などが必要です既定のレイクハウスはノートブックの先頭に以下のようなセルを構成すると、変数ライブラリの設定で切替も可能です。
https://learn.microsoft.com/ja-jp/fabric/data-engineering/author-execute-notebook#spark-session-configuration-magic-commandなお、Filesにアクセスしない場合は、既定のレイクハウスは必須ではありません。以下のいずれかの記法でアクセス可能です。
※スキーマ有効なレイクハウス
[`ワークスぺース名`].[`レイクハウス名`].[`スキーマ名`].[`テーブル名`]
[`レイクハウス名`].[`スキーマ名`].[`テーブル名`]
※スキーマ有効でないレイクハウス
[`レイクハウス名`].[`テーブル名`]
https://learn.microsoft.com/ja-jp/fabric/data-engineering/lakehouse-schemas#lakehouse-schemas-in-notebook -
ノートブックを実行します。
-
Notebook を実行すると、Lakehouse 上にテーブルと Materialized Lake View が作成されます。
テーブル内容
リネージ
Semantic Model と Report を作成する
-
セマンティックモデルを作成
レイクハウスのリボンから選択
任意の名前設定でgoldテーブルを選択する
ノートブックと紐づけたレイクハウスから作成します。
今回は開発ワークスペースのレイクハウスを選択しました。
テーブルが表示されない場合は、SQL分析エンドポイント側の表示を確認します -
レポートを作成
レポートの内容はなんでもOK
-
ワークスペース画面に戻り、
Applicationフォルダを作成
-
Application フォルダに移動します。
変更をコミットし、mainブランチに統合する
-
作成後、Fabric のソース管理から変更を Azure DevOps Repos にコミットします。
-
DevOpsに反映されます。
-
Create a pull request により、ブランチを統合します。
-
開発ワークスペースでソースの更新を取り込みます
3. 本番用 Fabric ワークスペースを作成する
次に、本番用の Fabric ワークスペースを作成します。
セットアップ
-
ワークスペースを作成します。
なお、git構成はprodでは使用しません。 -
作成後、Azure DevOps のサービス接続で使用しているサービスプリンシパルを、本番用ワークスペースの管理者として追加します。
-
次の作業用に、本番用ワークスペースの URL から Workspace ID を取得します。
Fabric ワークスペースの URL には、次のようにgroups/<workspace_guid>が含まれます。https://app.fabric.microsoft.com/groups/<workspace_guid>/...この
<workspace_guid>を控えておきます。
4. リリースパイプラインの作成
Azure DevOps Environment を作成する
-
Azure DevOps で、Pipeline の実行先となる Environment を作成します。
今回は本番環境用に、
PRODという名前で作成します。
-
(option) 承認ゲートを設ける場合は、Approvalsを追加します。
承認をした場合のみパイプラインのステップが進むように構成できます。
Azure DevOps 変数グループを作成する
-
Pipeline で使用する変数グループを作成します。
変数グループ名は
.azuredevops/pipelines/deploy-ws-holws-prod.ymlの内容と一致するようにします。.azuredevops\pipelines\deploy-ws-holws-prod.ymlvariable_group_name: 'deploy-holws-prod'
-
値を設定します。
サンプルリポジトリには、変数グループ用のテンプレートがあります。.azuredevops/variable-groups/workspace-deploy/template.varsこれを参考に、Azure DevOps の変数グループへ次の変数を登録します。
変数名 設定例 説明 workspace_guid12345678-1234-1234-1234-123456789abc本番用 Fabric ワークスペースの GUID vl_vset_activePRODFabric Variable Library で使用する Value Set 名 repo_project_directoryworkspaces/hol_ws/srcFabric アイテム定義があるリポジトリ内のパス fabric_item_type_inscope空欄 デプロイ対象の Fabric アイテムタイプ。空欄の場合は全アイテムを対象にする想定 私の環境の設定例です。
特定のアイテムタイプだけをデプロイしたい場合は、
fabric_item_type_inscopeにカンマ区切りで指定します。例：
Notebook Notebook,DataPipeline Lakehouse,Warehouse Notebook,SemanticModel,Report
Pipeline YAML を確認する
サンプルリポジトリには、次の Pipeline 定義ファイルが含まれています。
.azuredevops/pipelines/deploy-ws-holws-prod.yml
この YAML では、変数グループ名と Azure サービス接続名を参照します。
必要に応じて、次の値を自分の環境に合わせて変更します。
variable_group_name: deploy-ws-holws-prod
azure_service_connection_name: sc-fabric-cicd
特に、azure_service_connection_name は Azure DevOps で作成したサービス接続名と一致させてください。
Azure DevOps Pipeline を作成する
-
Azure DevOps の Pipelines から新しい Pipeline を作成します。
-
ソースとして Azure Repos Git を選択し、インポートしたリポジトリを選びます。
-
既存の YAML ファイルを使用し、次の YAML を指定します。
.azuredevops/pipelines/deploy-ws-holws-prod.yml
-
確認後、Pipeline を実行します。
初回実行時は、変数グループやサービス接続の使用許可を求められる場合があります。その場合は、Pipeline から使用できるように許可します。
Environmentで承認を入れていた場合には承認をします。
5. 初回デプロイ結果を確認
Pipeline が成功すると、本番用ワークスペースに Fabric アイテムが作成されます。
本番用ワークスペースを開き、次のアイテムがデプロイされていることを確認します。
- Lakehouse
- Notebook
- Environment
- Variable Library
- Semantic Model
- Report
また、Variable Library のアクティブな Value Set が PROD を向いていることを確認します。
一方で、この時点では次のような状態になっているはずです。
- Notebook の既定のLakehouse が開発用ワークスペースの Lakehouse を向いている
- Semantic Model の 参照先 が開発用ワークスペースの Lakehouse を向いている
これは、Notebook や Semantic Model の定義内に、開発用ワークスペースの GUID や Lakehouse GUID が含まれているためです。
変数ライブラリで対応しきれないような環境依存値を置き換えるために、次に parameter.yml を設定します。
6. parameter.ymlによる環境差分の吸収
fabric-cicd では、parameter.yml を使用して、デプロイ時に環境依存の値を置き換えることができます。
fabric-cicd - Parameterization
ファイルの配置
サンプルリポジトリには、テンプレートファイルがあります。
workspaces/template_parameter.yml
このファイルをコピーし、対象ワークスペースの src フォルダ直下に配置します。
workspaces/hol_ws/src/parameter.yml
Azure DevOps の Web UI では、次のように設定します。
-
ファイル作成
-
内容をtemplate_parameter.ymlからコピー
-
lakehouse_name のプレースホルダを置換(4か所あります)
<lakehouse_name>は、デプロイ先ワークスペースに存在する Lakehouse アイテム名に置き換えます。例：
PROD: "$items.Lakehouse.LH_CICD.$id"
-
コミット
作成する parameter.yml の例です。
find_replace:
# --------------------------------------------------------------------------
# Notebook: 既定 Lakehouse ID の置換
# --------------------------------------------------------------------------
# Notebook のメタデータに含まれる default_lakehouse の GUID を、
# デプロイ先環境の Lakehouse ID に置き換えます。
#
# <lakehouse_name> は、デプロイ先ワークスペース上の Lakehouse アイテム名に
# 置き換えてください。
# 例: "$items.Lakehouse.LH_CICD.$id"
- find_value: \#\s*META\s+"default_lakehouse":\s*"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"
replace_value:
PPE: "$items.Lakehouse.LH_CICD.$id"
PROD: "$items.Lakehouse.LH_CICD.$id"
is_regex: "true"
item_type: "Notebook"
# item_name: ["NB_sample"]
# --------------------------------------------------------------------------
# Notebook: 既定 Lakehouse Workspace ID の置換
# --------------------------------------------------------------------------
# Notebook のメタデータに含まれる default_lakehouse_workspace_id の GUID を、
# デプロイ先ワークスペース ID に置き換えます。
- find_value: \#\s*META\s+"default_lakehouse_workspace_id":\s*"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})"
replace_value:
PPE: "$workspace.$id"
PROD: "$workspace.$id"
is_regex: "true"
item_type: "Notebook"
# item_name: ["NB_sample"]
# --------------------------------------------------------------------------
# Semantic Model: OneLake URL 内の Workspace GUID の置換
# --------------------------------------------------------------------------
# Semantic Model の Power Query / M 定義に含まれる OneLake URL から、
# Workspace GUID の部分をデプロイ先ワークスペース ID に置き換えます。
#
# item_name には、対象の Semantic Model アイテム名を指定します。
- find_value: AzureStorage\.DataLake\("https://onelake\.dfs\.fabric\.microsoft\.com/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})/
replace_value:
PPE: "$workspace.$id"
PROD: "$workspace.$id"
is_regex: "true"
item_type: "SemanticModel"
# item_name: ["SM_CostInsight_OL"]
# --------------------------------------------------------------------------
# Semantic Model: OneLake URL 内の Lakehouse GUID の置換
# --------------------------------------------------------------------------
# Semantic Model の Power Query / M 定義に含まれる OneLake URL から、
# Lakehouse GUID の部分をデプロイ先環境の Lakehouse ID に置き換えます。
#
# <lakehouse_name> は、デプロイ先ワークスペース上の Lakehouse アイテム名に
# 置き換えてください。
- find_value: AzureStorage\.DataLake\("https://onelake\.dfs\.fabric\.microsoft\.com/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})
replace_value:
PPE: "$items.Lakehouse.LH_CICD.$id"
PROD: "$items.Lakehouse.LH_CICD.$id"
is_regex: "true"
item_type: "SemanticModel"
# item_name: ["SM_CostInsight_OL"]
parameter.yml のポイント
この parameter.yml では、主に次の値を置き換えています。
Notebook の既定のLakehouse IDとWorkspace ID
Notebook のメタデータには、既定 Lakehouse の GUIDと既定 Lakehouse が存在する Workspace ID が含まれます。
そのため、次の指定で本番用 Lakehouse の ID に置き換えています。
"$items.Lakehouse.<lakehouse_name>.$id"
"$workspace.$id"
Semantic Model の OneLake URL
Semantic Model の Power Query / M 定義には、OneLake on Direct Lake の場合にOneLake の URL が含まれます。（DirectLake on SQL の場合にはSQL 分析エンドポイントなどの接続文字列）
例：
https://onelake.dfs.fabric.microsoft.com/<workspace_guid>/<lakehouse_guid>/...
この URL に含まれる Workspace GUID と Lakehouse GUID を、本番用ワークスペースの値に置き換えています。
再度 Pipeline を実行する
parameter.yml をコミットしたら、Azure DevOps Pipeline を再実行します。
実行の完了後、それぞれのアイテムがprodのワークスペースのレイクハウスを参照していることを確認します。
ノートブックは開発環境のレイクハウスはknown lakehouseというメタデータで残るため、このような状態となりますが、既定のレイクハウスが変更できていればOKです。
まとめ
この記事では、fabric-cicd と Azure DevOps Pipeline を使用して、Microsoft Fabric ワークスペースのアイテムを本番用ワークスペースへデプロイする流れを紹介しました。
Fabric の CI/CD では、単にアイテムをコピーするだけでなく、環境ごとの差分をどう扱うかが重要です。
特に Notebook の既定 Lakehouse や Semantic Model の OneLake URL は、開発環境の値が残りやすいため、parameter.yml による置換を組み合わせることで、より実運用に近いデプロイ構成を作ることができます。
参考
-
fabric-cicd documentation
https://microsoft.github.io/fabric-cicd/ -
Microsoft Learn: Fabric-cicd Python library
https://learn.microsoft.com/ja-jp/rest/api/fabric/articles/fabric-ci-cd -
Microsoft Learn: CI/CD for Microsoft Fabric using Azure DevOps and fabric-cicd
https://learn.microsoft.com/ja-jp/fabric/cicd/tutorial-fabric-cicd-azure-devops -
Microsoft Learn: Identity support for Microsoft Fabric REST APIs
https://learn.microsoft.com/ja-jp/rest/api/fabric/articles/identity-support -
Microsoft Learn: Fabric Git integration process
https://learn.microsoft.com/ja-jp/fabric/cicd/git-integration/git-integration-process -
サンプルリポジトリ
https://github.com/ryoma-nagata/fabric-cicd-template