Databricksワークスペース移行ツール

あるワークスペースのアセットを別のワークスペースに移行したいというケースがあると思います。その際に活用できる移行ツールがGithubで公開されています。

上のツールのREADMEを翻訳したものとなります。2023/2/3時点のものです。

本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。

前提条件

移行ツールを使用するには以下が必要となります:

• python、pip、git、databricks CLIがインストールされているLinux環境。
• パーソナルアクセストークンを用いて新旧のアカウントにアクセスできる管理者権限。

セットアップ

トークンの生成

新旧両方のDatabricksアカウントでアクセストークンを生成してください。

1. Databricks画面の右上からUser settingsにアクセス。
2. Access Tokensタブをクリック。
3. Generate New Tokenボタンをクリック。
4. 生成したトークンをコピーし、セキュアな場所に保存。

新旧両方のDatabricksアカウントのURL、トークン、インスタンスIDをファイルに保存するようにしてください。移行ツールを実行する際に、これらすべての情報に容易にアクセスできるようになります。

databricks-cliのプロファイルのセットアップ

Linuxシェルから移行ツールを実行するには:

以下を実行して旧ワークスペースのプロファイルを作成します。

databricks configure --token --profile oldWS

この場合、旧Databricksアカウントで移行ツールexport_db.pyファイルを実行する際に参照するプロファイル名がoldWSとなります。

databricks cliコマンドを使用する際、2回プロンプトが表示されます

1. Databricks Host (should begin with https://): 表示された際には、上のファイルで記録した旧DatabricksワークスペースのURLを入力します。
2. Token: 表示された際には、旧Databricksアカウントで生成したトークンを貼り付けます。

新規のDatabricksアカウントに対して上のステップを繰り返し、どのアカウントからエクスポートし、どのアカウントにインポートするのかを追跡できるように、プロファイル名をnewWSのようなものにします。

以下を実行して新ワークスペースのプロファイルを作成します。

databricks configure --token --profile newWS

プロファイル名がnewWSの場合、新規のDatabricksアカウントで移行ツールimport_db.pyを実行する際に参照します。

依存パッケージのインストール

Python環境をセットアップするために、トップレベルのプロジェクトディレクトリからこのリポジトリをクローンし、python3 setup.py instalを実行します。

移行コンポーネント

移行ツールを使うに際し、ファイルを適切に移行するために推奨されるツールを実行するために以下の詳細を参照してください。

インポート、エクスポートオペレーションでサポート範囲を示すマトリクスです。

コンポーネント	エクスポート	インポート
Users / Groups	サポート	サポート
Clusters (w/ ACLs)	サポート	サポート
Notebooks (w/ ACLs)	サポート	サポート
Repos (w/ ACLs)	サポート	サポート
Metastore	サポート	サポート
Jobs (w/ ACLs)	サポート	サポート
Libraries	サポート	未サポート
Secrets	サポート	サポート
Table ACLs	サポート	サポート
DBFS Mounts	サポート	未サポート
ML Models	サポート*	サポート*

MLflow移行に関する注意
MLflowアセットの移行のサポートは部分的なものです。Feature StoreとModel Registryは移行されません。包括的なMLflow移行についてはmlflow-export-importをご覧下さい。

DBFSデータ移行に関する注意
DBFSはAWSやAzureにおいて保護されたオブジェクトストレージロケーションです。DBFSリソースの移行に関してはDatabricksサポートにコンタクトしてください。

ユーザー移行に関する注意
ユーザー/グループのインポートにおいては、デフォルトでは新規ワークスペースがユーザーに通知されます。この挙動を無効化したい場合には、Databricksアカウントチームにお問い合わせください。

パイプラインを用いたインポート

推奨の方法は、migration_pipeline.pyに格納されているパイプラインを用いてエクスポート、インポートを行うことです。このパイプラインは、順序を追ってすべてのエクスポートとインポートステップを実行し、チェックポイントの並列化機能も搭載しています。

パイプラインのパラメータ

python migration_pipeline.py -h
usage: migration_pipeline.py [-h] [--profile PROFILE] [--azure or gcp] [--silent] [--no-ssl-verification] [--debug] [--set-export-dir SET_EXPORT_DIR]
                             [--cluster-name CLUSTER_NAME] [--notebook-format {DBC,SOURCE,HTML}] [--overwrite-notebooks] [--archive-missing]
                             [--repair-metastore-tables] [--metastore-unicode] [--skip-failed] [--session SESSION] [--dry-run] [--export-pipeline] [--import-pipeline]
                             [--validate-pipeline] [--validate-source-session VALIDATE_SOURCE_SESSION] [--validate-destination-session VALIDATE_DESTINATION_SESSION]
                             [--use-checkpoint] [--skip-tasks SKIP_TASKS [SKIP_TASKS ...]] [--num-parallel NUM_PARALLEL] [--retry-total RETRY_TOTAL]
                             [--retry-backoff RETRY_BACKOFF] [--start-date START_DATE]
                             [--exclude-work-item-prefixes EXCLUDE_WORK_ITEM_PREFIXES [EXCLUDE_WORK_ITEM_PREFIXES ...]]

Export user(s) workspace artifacts from Databricks

optional arguments for import/export pipeline:
  -h, --help            show this help message and exit
  --profile PROFILE     Profile to parse the credentials
  --azure or --gcp      Run on Azure or GCP (Default is AWS)
  --silent              Silent all logging of export operations.
  --no-ssl-verification
                        Set Verify=False when making http requests.
  --debug               Enable debug logging
  --no-prompt           Skip interactive prompt/confirmation for workspace import.
  --set-export-dir SET_EXPORT_DIR
                        Set the base directory to export artifacts
  --cluster-name CLUSTER_NAME
                        Cluster name to export the metastore to a specific cluster. Cluster will be started.
  --notebook-format {DBC,SOURCE,HTML}
                        Choose the file format to download the notebooks (default: DBC)
  --overwrite-notebooks
                        Flag to overwrite notebooks to forcefully overwrite during notebook imports
  --archive-missing     Import all missing users into the top level /Archive/ directory.
  --repair-metastore-tables
                        Repair legacy metastore tables
  --metastore-unicode   log all the metastore table definitions including unicode characters
  --skip-failed         Skip retries for any failed hive metastore exports.
  --skip-missing-users  Skip failed principles during ACL import; for missing principles, this will result in open ACLs
  --session SESSION     If set, pipeline resumes from latest checkpoint of given session; Otherwise, pipeline starts from beginning and creates a new session.
  --dry-run             Dry run the pipeline i.e. will not execute tasks if true.
  --export-pipeline     Execute all export tasks.
  --import-pipeline     Execute all import tasks.
  --use-checkpoint      use checkpointing to restart from previous state
  --skip-tasks SKIP_TASK [SKIP_TASK ...]
                        Space-separated list of tasks to skip from the pipeline. Valid options are:
                         instance_profiles, users, groups, workspace_item_log, workspace_acls, notebooks, secrets,
                         clusters, instance_pools, jobs, metastore, metastore_table_acls, mlflow_experiments, mlflow_runs
  --keep-tasks KEEP_TASK [KEEP_TASK ...]
                        Space-separated list of tasks to run from the pipeline. See valid options in --skip-tasks. Overrides skip-tasks.
  --num-parallel NUM_PARALLEL
                        Number of parallel threads to use to export/import
  --retry-total RETRY_TOTAL
                        Total number or retries when making calls to Databricks API
  --retry-backoff RETRY_BACKOFF
                        Backoff factor to apply between retry attempts when making calls to Databricks API
  --start-date START_DATE
                        start-date format: YYYY-MM-DD. If not provided, defaults to past 30 days. Currently, only used for exporting ML runs objects.
  --groups-to-keep group [group ...]
                        List of groups to keep if selectively exporting assets. Only users (and their assets) belonging to these groups will be exported.
                        
options for validation pipeline:
  --validate-pipeline   Validate exported data between source and destination.
  --validate-source-session VALIDATE_SOURCE_SESSION
                        Session used by exporting source workspace. Only used for --validate-pipeline.
  --validate-destination-session VALIDATE_DESTINATION_SESSION
                        Session used by exporting destination workspace. Only used for --validate-pipeline.

ワークスペースのエクスポート

ワークスペースをエクスポートするには、以下を実行します。

python3 migration_pipeline.py --profile $SRC_PROFILE --export-pipeline --use-checkpoint [--session $SESSION_ID]

$SRC_PROFILEは、セットアップで設定したソースワークスペースに対するDatabricksプロファイル、$SESSION_IDは移行のチェックポイント実行で使用されるオプションのセッションIDです。すべてのデータは、logsフォルダ配下に$SESSION_IDという名前のフォルダにエクスポート(“logs/$SESSION_ID”)されます。$SESSION_IDが指定されない場合、ランダムな値が生成されます。

パラメータの推奨値およびチェックポイント

スタート地点として、以下のパラメータを使用することをお勧めします。

• retry-total=30
• num-parallel=8
• retry-backoff=1.0

必要に応じて、シナリオに合わせて調整することが可能です。通常はAPI制限に到達した場合には、retry-backoffを増やすか、num-parallelを減らします。

スクリプトのエラーが発生する場合には、以前のチェックポイントを特定し再実行するために、--use-checkpointと--session $SESSION_IDを用いて安全に同じコマンドを再実行することができます。

AWSアカウントIDの更新

ソースワークスペースとターゲットワークスペースが別のアカウントに存在している場合、移行期間中にインスタンスプロファイルのARNを更新する必要があります。これを行うには、ワークスペースのアセットをエクスポートした後に以下のコマンドを実行します。

python3 export_db.py --profile $SRC_PROFILE --use-checkpoint --old-account-id $OLD_AWS_ACCT_ID --update-account-id $NEW_AWS_ACCT_ID --set-export-dir $EXPORT_DIR/$SESSION_ID

EXPORT_DIR/SESSION_IDはエクスポートジョブの実行時に使用したディレクトリとセッションIDであり、SRC_PROFILEはソースワークスペースをエクスポートする際に使用したプロファイル、OLD_AWS_ACCT_IDはソースのAWSアカウントID、NEW_AWS_ACCT_IDはターゲットのAWSアカウントIDです。これはインスタンスプロファイルのARNのみを更新することに注意してください。同じインスタンスプロファイルは依然としてターゲットワークスペースに存在しなくてはなりません。

ワークスペースのインポート

ターゲットワークスペースにインポートするためには、以下を実行します。

python3 migration_pipeline.py --profile $DST_PROFILE --import-pipeline --use-checkpoint [--session $SESSION_ID]

上述した同じ推奨パラメータがインポートワークフローにも適用され、同様にエラーが起きた際には、--use-checkpointを用いて最後のチェックポイントから再開することができます。

検証

インポートが完了した後に、最初にターゲットワークスペースのコンテンツをエクスポートすることで、シンプルなワークスペースオブジェクトの検証を実行することができます。

python3 migration_pipeline.py --profile $DST_PROFILE --export-pipeline --use-checkpoint --cluster-name

そして、validate_pipeline.shを実行します。

./validate_pipeline.sh $SRC_EXPORT_SESSION_ID $DST_EXPORT_SESSION_ID

完了したら、コンソール上のサマリーとlogsフォルダ(新規のフォルダが生成されているはずです)を確認してください。

ステップバイステップツールを用いたインポート(非推奨)

原文をご覧ください。

制限

注意
SSLの検証を無効化するには、--no-ssl-verificationを指定してください。依然としてSSLエラーに遭遇する際には、現在のbashシェルに以下を追加してください。

export REQUESTS_CA_BUNDLE=""
export CURL_CA_BUNDLE=""

• インスタンスプロファイル(AWSのみ): インスタンスプロファイルに対するグループのアクセスが優先されます。ロールにユーザーが直接追加され、グループ経由でのアクセス権がある場合、移行の際にはグループのみのアクセスが許可されます。
• クラスター: クラスターの作成者は、すべてのクラスターを移行した単一の管理者ユーザーとして表示されます。(課金目的では適切です)
  • クラスター作成者のタグは更新されません。DBU追跡のためにOriginalCreatorというカスタムタグが追加されます。
• ジョブ: ジョブの作成者は、すべてのクラスターを移行した単一の管理者ユーザーとして表示されます。(課金目的では適切です)
  • 存在しない既存クラスターを持つジョブはデフォルトクラスタータイプにリセットされます。
  • 古いレガシーインスタンスを持つジョブは、未サポートDBRや未サポートのインスタンスタイプでエラーとなります。最新のサポートリリースについてはリリースノートをご覧ください。

Databricks 無料トライアル

Databricks 無料トライアル