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

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

概要

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

ベースコンテナは、ホスト仮想マシン（VM）の Container-Optimized OS で構成されます。ホストイメージは cos-stable イメージファミリーからビルドされます。

制限事項

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

カスタムコンテナは、Google 提供のベースコンテナから派生したものである必要があります。ベースコンテナから派生していないコンテナを使用すると、互換性の問題が発生するリスクが高まり、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 ストリーミングサービスとの互換性を確保するために必要です。メタデータ値を使用して追加されるコンテナパラメータは、nerdctl でサポートされているものに準拠する必要があります。
Vertex AI Workbench インスタンスは、Artifact Registry または公開コンテナリポジトリから pull するように構成されています。非公開リポジトリから pull するようにインスタンスを構成するには、containerd で使用される認証情報を手動で構成する必要があります。

ベースコンテナ

標準ベースコンテナ

標準ベースコンテナは、Vertex AI Workbench のすべての機能をサポートし、次のものを含みます。

プリインストールされたデータサイエンスパッケージ。
Deep Learning Containers に類似した Cuda ライブラリ。
Google Cloud JupyterLab の統合（Dataproc や BigQuery の統合など）。
curl や git などの一般的なシステムパッケージ。
メタデータベースの JupyterLab 構成。
Micromamba ベースのカーネル管理。

仕様

標準ベースコンテナの仕様は次のとおりです。

ベースイメージ: nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
画像サイズ: 約 22 GB
URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

スリムベースコンテナ

スリムなベースコンテナには、インスタンスへのプロキシ接続を許可する最小限の構成セットが用意されています。標準の Vertex AI Workbench の機能とパッケージは、次のものを除き、含まれていません。

JupyterLab
メタデータベースの JupyterLab 構成
Micromamba ベースのカーネル管理

追加のパッケージまたは JupyterLab 拡張機能は、個別にインストールして管理する必要があります。

仕様

スリムベースコンテナの仕様は次のとおりです。

ベースイメージ: marketplace.gcr.io/google/ubuntu24.04
画像サイズ: 約 2 GB
URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

始める前に

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.

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

必要なロール

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

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

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

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

カスタムコンテナの作成

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

Google 提供のベースコンテナイメージから派生した派生コンテナを作成します。
コンテナをビルドして Artifact Registry に push します。Vertex AI Workbench インスタンスを作成するときに、コンテナの URI を使用します。たとえば、URI は gcr.io/PROJECT_ID/IMAGE_NAME のようになります。

インスタンスを作成する

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

コンソール

カスタムコンテナに基づいて Vertex AI Workbench インスタンスを作成するには、次の操作を行います。

Google Cloud コンソールで [インスタンス] ページに移動します。

[インスタンス] に移動
[新規作成] をクリックします。
[新しいインスタンス] ダイアログで、[詳細オプション] をクリックします。
[インスタンスの作成] ダイアログの [環境] セクションで、[カスタムコンテナを使用する] を選択します。
[Docker コンテナイメージ] で [選択] をクリックします。
[コンテナイメージの選択] ダイアログで、使用するコンテナイメージに移動し、[選択] をクリックします。
省略可。[起動後のスクリプト] に、使用する起動後のスクリプトへのパスを入力します。
省略可。インスタンスのメタデータを追加します。詳細については、カスタムコンテナメタデータをご覧ください。
省略可。[ネットワーキング] セクションで、ネットワーク設定をカスタマイズします。詳細については、ネットワーク構成オプションをご覧ください。
インスタンス作成ダイアログの残りの部分に入力して、[作成] をクリックします。

Vertex AI Workbench がインスタンスを作成し、自動的に起動します。インスタンスを使用する準備が整うと、Vertex AI Workbench で [JupyterLab を開く] が有効になります。

gcloud

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

INSTANCE_NAME: Vertex AI Workbench インスタンスの名前。先頭は英字で、それに続く最大 62 文字の英小文字、数字、ハイフン（-）で構成します。末尾にハイフンは使用できません。
PROJECT_ID: プロジェクト ID
LOCATION: インスタンスを配置するゾーン
CUSTOM_CONTAINER_PATH: コンテナイメージリポジトリのパス（例: gcr.io/PROJECT_ID/IMAGE_NAME）
METADATA: このインスタンスに適用するカスタムメタデータ。たとえば、起動後スクリプトを指定するには、post-startup-script メタデータタグを "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh" の形式で使用してください。

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

Linux、macOS、Cloud Shell

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

Windows（PowerShell）

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

Windows（cmd.exe）

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

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

Vertex AI Workbench がインスタンスを作成し、自動的に起動します。インスタンスを使用する準備が整うと、 Google Cloud コンソールの [JupyterLab を開く] リンクが Vertex AI Workbench により有効化されます。

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

カスタムコンテナを使用する 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 パッケージがプリインストールされた新しいカーネルを作成する方法を示しています。

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

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"

新しいコンテナを 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

インスタンスの作成

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

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

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

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

micromamba 環境を作成します。

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

次のように置き換えます。

USER: ユーザーディレクトリ名（デフォルトは jupyter）
ENVIRONMENT_NAME: 環境の名前。
PYTHON_VERSION: Python のバージョン（3.11 など）

カーネルが更新されるまで 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

CP startup_file.sh /
# Ensure that you have the correct permissions and startup is executable.
RUN chmod 755 /startup_file.sh && \
    chown jupyter:jupyter /startup_file.sh

# 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 インスタンスに適用できるメタデータの標準リストに加えて、カスタムコンテナを使用するインスタンスには、ペイロードコンテナのインスタンス化を管理するための次のメタデータが含まれます。

機能	説明	メタデータキー	使用可能な値とデフォルトの値
コンテナイメージで Cloud Storage FUSE を有効にする	`/dev/fuse` をコンテナにマウントし、`gcsfuse` を有効にして、コンテナで使用できるようにします。	`container-allow-fuse`	`true`: Cloud Storage FUSE を有効にします。 `false`（デフォルト）: Cloud Storage FUSE を有効にしません。
追加のコンテナ実行パラメータ	追加のコンテナパラメータを `nerdctl run` に追加します。ここで、`nerdctl` は Containerd CLI です。	`container-custom-params`	コンテナ実行パラメータの文字列。例: `--v /mnt/disk1:/mnt/disk1`。
その他のコンテナ環境フラグ	環境変数を `/mnt/stateful_partition/workbench/container_env` のフラグに保存し、`nerdctl run` に追加します。	`container-env-file`	コンテナの環境変数の文字列。例: `CONTAINER_NAME=derivative-container`。

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

インスタンスが初めて起動すると、custom-container-payload メタデータに保存されている URI からコンテナイメージが pull されます。:latest タグを使用すると、コンテナは再起動ごとに更新されます。custom-container-payload メタデータ値は保護されたメタデータキーであるため、直接変更することはできません。

インスタンスのカスタムコンテナイメージを更新するには、Google Cloud CLI、Terraform、または Notebooks API でサポートされている次の方法を使用します。

gcloud

Vertex AI Workbench インスタンスのカスタムコンテナイメージメタデータを更新するには、次のコマンドを使用します。

gcloud workbench instances update INSTANCE_NAME \
    --container-repository=CONTAINER_URI \
    --container-tag=CONTAINER_TAG

Terraform

Terraform 構成の container_image フィールドを変更して、コンテナペイロードを更新できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    container_image {
      repository = "us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container"
      family  = "latest"
    }
  }
}

Notebooks API

updateMask の gce_setup.container_image.repository と gce_setup.container_image.tag を変更して、instances.patch メソッドを使用します。

診断ツールを実行する

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

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

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

SSH を使用して Vertex AI Workbench インスタンスに接続します。
SSH ターミナルで、次のコマンドを実行します。
```
sudo docker exec diagnostic-service ./diagnostic_tool
```
その他のコマンドオプションを表示するには、次のコマンドを実行します。
```
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: インスタンスが配置されているゾーン

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

Linux、macOS、Cloud Shell

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

Windows（PowerShell）

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

Windows（cmd.exe）

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 のドキュメントをご覧ください。

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

概要

制限事項

ベースコンテナ

標準ベースコンテナ

仕様

スリム ベース コンテナ

仕様

始める前に

必要なロール

カスタム コンテナの作成

インスタンスを作成する

コンソール

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

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

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

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

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

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

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

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

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

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

gcloud

Terraform

Notebooks API

診断ツールを実行する

インスタンスにアクセスする

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

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

スリムベースコンテナ

カスタムコンテナの作成

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

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

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

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

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

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