カスタム コンテナを使用してインスタンスを作成する

このページでは、カスタム コンテナに基づいて Vertex AI Workbench インスタンスを作成する方法について説明します。

概要

Vertex AI Workbench インスタンスは、Google 提供のベースコンテナから派生したカスタム コンテナの使用をサポートしています。このベースコンテナを変更してカスタム コンテナ イメージを作成し、このカスタム コンテナを使用して Vertex AI Workbench インスタンスを作成できます。

ベースコンテナは、ホスト仮想マシン（VM）の Container-Optimized OS で構成されます。ベースコンテナには、プリインストールされたデータ サイエンス パッケージと、インスタンスが Google Cloud と統合できるようにする特定の構成が用意されています。

ベースコンテナは gcr.io/deeplearning-platform-release/workbench-container:latest にあります。

制限事項

プロジェクトを計画する際は、次の制限事項を考慮してください。

• カスタム コンテナは、Google 提供のベースコンテナ（gcr.io/deeplearning-platform-release/workbench-container:latest）から派生したものである必要があります。ベースコンテナから派生していないコンテナを使用すると、互換性の問題が発生するリスクが高まり、Vertex AI Workbench インスタンスの使用をサポートする機能が制限されます。

• Vertex AI Workbench インスタンスで複数のコンテナを使用することはできません。

• ユーザー管理ノートブックとマネージド ノートブックのカスタム コンテナでサポートされるメタデータは、Vertex AI Workbench インスタンスで使用した場合に異なる動作をすることがあります。

• カスタム コンテナをホストする VM は Container-Optimized OS で実行されているため、ホストマシンへの操作方法が制限されます。たとえば、Container-Optimized OS にはパッケージ マネージャーが含まれていません。つまり、ホスト上で動作するパッケージは、マウントされたコンテナで実行する必要があります。これは、マネージド ノートブック インスタンスとユーザー管理ノートブック インスタンスから移行された起動後のスクリプトに影響します。ホストマシンには、Container-Optimized OS よりもはるかに多くのツールが含まれています。

• Vertex AI Workbench インスタンスは、nerdctl（containerd CLI）を使用してカスタム コンテナを実行します。これは、Image Streaming サービスとの互換性を確保するために必要です。メタデータ値を使用して追加されるコンテナ パラメータは、nerdctl でサポートされているものに準拠する必要があります。

• Vertex AI Workbench インスタンスは、Artifact Registry または公開コンテナ リポジトリから pull するように構成されています。非公開リポジトリから pull するようにインスタンスを構成するには、containerd で使用される認証情報を手動で構成する必要があります。

始める前に

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Notebooks API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Notebooks API.

   Enable the API

必要なロール

カスタム コンテナを使用して Vertex AI Workbench インスタンスを作成するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• ユーザー アカウントに対する Notebooks 実行者 （roles/notebooks.runner）
• Artifact Registry リポジトリからイメージを pull するには、サービス アカウントに対する Artifact Registry 読み取り （roles/artifactregistry.reader）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

カスタム コンテナの作成

Vertex AI Workbench インスタンスで使用するカスタム コンテナを作成するには:

1. Google 提供のベースコンテナ イメージ（gcr.io/deeplearning-platform-release/workbench-container:latest）から派生した派生コンテナを作成します。

2. コンテナをビルドして Artifact Registry に push します。Vertex AI Workbench インスタンスを作成するときに、コンテナの URI を使用します。たとえば、URI は gcr.io/PROJECT_ID/IMAGE_NAME のようになります。

インスタンスを作成する

カスタム コンテナに基づいて Vertex AI Workbench インスタンスを作成するには、Google Cloud コンソールまたは Google Cloud CLI を使用します。

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --container-repository=CUSTOM_CONTAINER_URL \
    --container-tag=latest \
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --container-repository=CUSTOM_CONTAINER_URL `
    --container-tag=latest `
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --container-repository=CUSTOM_CONTAINER_URL ^
    --container-tag=latest ^
    --metadata=METADATA

ネットワーク構成オプション

カスタム コンテナを使用する Vertex AI Workbench インスタンスは、一般的なネットワーク オプションに加えて、Artifact Registry サービスにアクセスできる必要があります。

VPC の公開 IP アクセスを無効にしている場合は、限定公開の Google アクセスが有効になっていることを確認します。

イメージ ストリーミングを有効にする

カスタム コンテナホストは、Google Kubernetes Engine（GKE）でイメージ ストリーミングとやり取りするようにプロビジョニングされます。これにより、コンテナの pull が高速化され、GKE リモート ファイル システムにキャッシュに保存された大規模なコンテナの初期化時間が短縮されます。

イメージ ストリーミングを有効にするための要件については、要件をご覧ください。多くの場合、Container File System API を有効にすることで、Vertex AI Workbench インスタンスでイメージ ストリーミングを使用できます。

Container File System API を有効にする

ホスト VM がカスタム コンテナを実行する方法

ホスト VM は、Docker を使用してカスタム コンテナを実行するのではなく、Kubernetes Namespace の nerdctl を使用してコンテナを読み込んで実行します。これにより、Vertex AI Workbench はカスタム コンテナに Image ストリーミングを使用できます。

# Runs the custom container.
sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container

インストール例: カスタム デフォルト カーネルを使用するカスタム コンテナ

次の例は、pip パッケージがプリインストールされた新しいカーネルを作成する方法を示しています。

1. 新しいカスタム コンテナを作成します。

   FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
   
   ENV MAMBA_ROOT_PREFIX=/opt/micromamba
   
   RUN micromamba create -n ENVIRONMENT_NAME -c conda-forge python=PYTHON_VERSION -y
   
   SHELL ["micromamba", "run", "-n", "ENVIRONMENT_NAME", "/bin/bash", "-c"]
   
   RUN micromamba install -c conda-forge pip -y
   RUN pip install PACKAGE
   RUN pip install ipykernel
   RUN python -m ipykernel install --prefix /opt/micromamba/envs/ENVIRONMENT_NAME --name ENVIRONMENT_NAME --display-name KERNEL_NAME
   # Creation of a micromamba kernel automatically creates a python3 kernel
   # that must be removed if it's in conflict with the new kernel.
   RUN rm -rf "/opt/micromamba/envs/ENVIRONMENT_NAME/share/jupyter/kernels/python3

2. 新しいコンテナを Artifact Registry に追加します。

   gcloud auth configure-docker REGION-docker.pkg.dev
   docker build -t REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME .
   docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest

3. インスタンスの作成

   gcloud workbench instances create INSTANCE_NAME  \
       --project=PROJECT_ID \
       --location=ZONE \
       --container-repository=REGION-docker.pkg.dev/PROJECT_ID/IMAGE_NAME \
       --container-tag=latest

カスタム コンテナの永続カーネル

Vertex AI Workbench カスタム コンテナは、各コンテナ内の /home/USER ディレクトリにのみデータディスクをマウントします。ここで、jupyter はデフォルト ユーザーです。つまり、/home/USER の外部で行われた変更はエフェメラルで、再起動後に保持されません。インストールされたパッケージを特定のカーネルに保持する必要がある場合は、/home/USER ディレクトリにカーネルを作成できます。

/home/USER ディレクトリにカーネルを作成するには:

1. micromamba 環境を作成します。

   micromamba create -p /home/jupyter/ENVIRONMENT_NAME -c conda-forge python=3.11 -y
   micromamba activate ENVIRONMENT_NAME
   pip install ipykernel
   pip install -r ~/requirement.txt
   python -m ipykernel install --prefix "/home/jupyter/ENVIRONMENT_NAME" --display-name "Example Kernel"

2. カーネルが更新されるまで 30 秒から 1 分ほど待ちます。

ベースコンテナの起動を更新する

Vertex AI Workbench インスタンスのベース コンテナ（us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest）は、/run_jupyter.sh を実行して JupyterLab を起動します。

派生コンテナでコンテナの起動を変更する場合は、/run_jupyter.sh を追加して JupyterLab のデフォルト構成を実行する必要があります。

Dockerfile を変更する方法の例を次に示します。

# DockerFile
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

# Override the existing CMD directive from the base container.
CMD ["/startup_file.sh"]

# /startup_file.sh

echo "Running startup scripts"
...

/run_jupyter.sh

ベースコンテナ内の JupyterLab 構成の更新

ベースコンテナの JupyterLab 構成を変更する必要がある場合は、次の操作を行う必要があります。

• JupyterLab がポート 8080 に構成されていることを確認します。プロキシ エージェントは、すべてのリクエストをポート 8080 に転送するように構成されています。Jupyter サーバーが正しいポートをリッスンしていない場合、インスタンスでプロビジョニングの問題が発生します。

• jupyterlab micromamba 環境で JupyterLab パッケージを変更します。JupyterLab とそのプラグインを実行するための個別のパッケージ環境が用意されており、カーネル環境との依存関係の競合がないようにしています。追加の JupyterLab 拡張機能をインストールする場合は、jupyterlab 環境内にインストールする必要があります。次に例を示します。

  # DockerFile
  FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
  RUN micromamba activate jupyterlab && \
    jupyter nbextension install nbdime

カスタム コンテナ メタデータ

Vertex AI Workbench インスタンスに適用できるメタデータの標準リストに加えて、カスタム コンテナを使用するインスタンスには、ペイロード コンテナのインスタンス化を管理するための次のメタデータが含まれます。

カスタム コンテナをアップグレードする

カスタム コンテナを更新する必要がある場合は、custom-container-payload メタデータ値を新しいコンテナ URI に更新します。コンテナの再起動ごとに、custom-container-payload に保存されている URI からコンテナの pull が試行されます。

:latest タグを使用すると、ベースコンテナは再起動ごとに更新されます。次の例をご覧ください。

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

ベースコンテナを更新しないようにするには、バージョンを指定します。次の例をご覧ください。

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:20240920-2200-rc0

診断ツールを実行します。

診断ツールは、さまざまな Vertex AI Workbench サービスのステータスを確認します。詳細については、診断ツールが実行するタスクをご覧ください。

カスタム コンテナを使用して Vertex AI Workbench インスタンスを作成する場合、診断ツールは、ユーザーが実行できるホスト環境のスクリプトとして使用できません。代わりに、バイナリにコンパイルされ、Container-Optimized OS 環境で診断サービスを実行するようにビルドされた Google ランタイム コンテナに読み込まれます。Container-Optimized OS の概要をご覧ください。

診断ツールの実行手順は次のとおりです。

1. SSH を使用して Vertex AI Workbench インスタンスに接続します。

2. SSH ターミナルで、次のコマンドを実行します。

   sudo docker exec diagnostic-service ./diagnostic_tool

3. その他のコマンド オプションを表示するには、次のコマンドを実行します。

   sudo docker exec diagnostic-service ./diagnostic_tool --help

診断ツールのオプションの詳細については、モニタリング ヘルス状態のドキュメントをご覧ください。

REST API を使用して診断ツールを実行するには、REST API のドキュメントをご覧ください。

インスタンスにアクセスできるようにする

プロキシ URL を使用してインスタンスにアクセスできます。

インスタンスが作成されてアクティブになったら、gcloud CLI を使用してプロキシ URL を取得できます。

後述のコマンドデータを使用する前に、次のように置き換えます。

• INSTANCE_NAME: Vertex AI Workbench インスタンスの名前
• PROJECT_ID: プロジェクト ID
• LOCATION: インスタンスが配置されているゾーン

次のコマンドを実行します。

gcloud workbench instances describe INSTANCE_NAME \
--project=PROJECT_ID \
--location=LOCATION | grep proxy-url

gcloud workbench instances describe INSTANCE_NAME `
--project=PROJECT_ID `
--location=LOCATION | grep proxy-url

gcloud workbench instances describe INSTANCE_NAME ^
--project=PROJECT_ID ^
--location=LOCATION | grep proxy-url

proxy-url: 7109d1b0d5f850f-dot-datalab-vm-staging.googleusercontent.com

describe コマンドによって、プロキシ URL が返されます。インスタンスにアクセスするには、ウェブブラウザでプロキシ URL を開きます。

コマンドラインでインスタンスを記述するコマンドの詳細については、gcloud CLI のドキュメントをご覧ください。