Membuat instance menggunakan container kustom

Halaman ini menjelaskan cara membuat instance Vertex AI Workbench berdasarkan container kustom.

Ringkasan

Instance Vertex AI Workbench mendukung penggunaan container kustom yang berasal dari salah satu container dasar yang disediakan Google. Anda dapat mengubah container dasar ini untuk membuat image container kustom dan menggunakan container kustom ini untuk membuat instance Vertex AI Workbench.

Container dasar dikonfigurasi dengan Container-Optimized OS di virtual machine (VM) host. Gambar host dibuat dari cos-stable kelompok gambar.

Batasan

Pertimbangkan batasan berikut saat merencanakan project Anda:

  • Container kustom harus berasal dari container dasar yang disediakan Google. Menggunakan container yang tidak berasal dari container dasar akan meningkatkan risiko masalah kompatibilitas dan membatasi kemampuan kami untuk mendukung penggunaan instance Vertex AI Workbench Anda.

  • Penggunaan lebih dari satu container dengan instance Vertex AI Workbench tidak didukung.

  • Metadata yang didukung untuk container kustom dari notebook yang dikelola pengguna dan notebook terkelola dapat memiliki perilaku yang berbeda saat digunakan dengan instance Vertex AI Workbench.

  • VM yang menghosting container kustom berjalan di Container-Optimized OS, yang membatasi cara Anda berinteraksi dengan mesin host. Misalnya, Container-Optimized OS tidak menyertakan pengelola paket. Artinya, paket yang bertindak di host harus dilakukan di container dengan pemasangan. Hal ini memengaruhi skrip pasca-startup yang dimigrasikan dari instance notebook terkelola dan instance notebook yang dikelola pengguna, yang mesin host-nya berisi lebih banyak alat daripada Container-Optimized OS.

  • Instance Vertex AI Workbench menggunakan nerdctl (CLI containerd) untuk menjalankan container kustom. Parameter ini diperlukan untuk kompatibilitas dengan layanan streaming Gambar. Parameter penampung yang ditambahkan menggunakan nilai metadata harus mematuhi apa yang didukung oleh nerdctl.

  • Instance Vertex AI Workbench dikonfigurasi untuk menarik dari Artifact Registry atau repositori container publik. Untuk mengonfigurasi instance agar menarik dari repositori pribadi, Anda harus mengonfigurasi kredensial yang digunakan oleh containerd secara manual.

Penampung dasar

Container dasar standar

Container dasar standar mendukung semua fitur Vertex AI Workbench dan mencakup hal berikut:

Spesifikasi

Container dasar standar memiliki spesifikasi berikut:

  • Gambar dasar: nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
  • Ukuran gambar: Sekitar 22 GB
  • URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

Penampung dasar ramping

Container dasar yang ramping menyediakan serangkaian konfigurasi minimal yang memungkinkan koneksi proxy ke instance. Fitur dan paket Vertex AI Workbench standar tidak disertakan, kecuali yang berikut:

  • JupyterLab
  • Konfigurasi JupyterLab berbasis metadata
  • Pengelolaan kernel berbasis Micromamba

Paket tambahan atau ekstensi JupyterLab harus diinstal dan dikelola secara terpisah.

Spesifikasi

Container dasar yang ramping memiliki spesifikasi berikut:

  • Gambar dasar: marketplace.gcr.io/google/ubuntu24.04
  • Ukuran gambar: Sekitar 2 GB
  • URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

Sebelum memulai

  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. Verify 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. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks API.

    Enable the API

    8.

    Peran yang diperlukan

    Untuk mendapatkan izin yang Anda perlukan untuk membuat instance Vertex AI Workbench dengan container kustom, minta administrator untuk memberi Anda peran IAM berikut:

    Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

    Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

    Membuat container kustom

    Untuk membuat container kustom yang akan digunakan dengan instance Vertex AI Workbench:

    1. Buat container turunan yang berasal dari image container dasar yang disediakan Google.

    2. Bangun dan kirim container ke Artifact Registry. Anda akan menggunakan URI container saat membuat instance Vertex AI Workbench. Misalnya, URI mungkin terlihat seperti ini: gcr.io/PROJECT_ID/IMAGE_NAME.

    Buat instance

    Anda dapat membuat instance Vertex AI Workbench berdasarkan container kustom menggunakan Google Cloud konsol atau Google Cloud CLI.

    Konsol

    Untuk membuat instance Vertex AI Workbench berdasarkan container kustom, lakukan hal berikut:

    1. Di konsol Google Cloud , buka halaman Instances.

      Buka Instance

    2. Klik  Buat baru.

    3. Dalam dialog Instance baru, klik Opsi lanjutan.

    4. Dalam dialog Create instance, di bagian Environment, pilih Use custom container.

    5. Untuk Docker container image, klik Select.

    6. Di dialog Select container image, buka image container yang ingin Anda gunakan, lalu klik Select.

    7. Opsional. Untuk Post-startup script, masukkan jalur ke skrip pasca-startup yang ingin Anda gunakan.

    8. Opsional. Tambahkan metadata untuk instance Anda. Untuk mempelajari lebih lanjut, lihat Metadata container kustom.

    9. Opsional. Di bagian Jaringan, sesuaikan setelan jaringan Anda. Untuk mempelajari lebih lanjut, lihat Opsi konfigurasi jaringan.

    10. Selesaikan dialog pembuatan instance selanjutnya, lalu klik Buat.

      Vertex AI Workbench membuat sebuah instance dan otomatis memulainya. Saat instance siap digunakan, Vertex AI Workbench akan mengaktifkan link Open JupyterLab.

    gcloud

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • INSTANCE_NAME: nama instance Vertex AI Workbench Anda; harus dimulai dengan huruf, diikuti dengan maksimal 62 huruf kecil, angka, atau tanda hubung (-), dan tidak boleh diakhiri dengan tanda hubung
    • PROJECT_ID: project ID Anda
    • LOCATION: zona tempat Anda ingin menempatkan instance
    • CUSTOM_CONTAINER_PATH: jalur ke repositori image container, misalnya: gcr.io/PROJECT_ID/IMAGE_NAME
    • METADATA: metadata kustom yang akan diterapkan ke instance ini; misalnya, guna menentukan post-startup-script, Anda dapat menggunakan tag metadata post-startup-script, dalam format: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

    Jalankan perintah berikut:

    Linux, macOS, atau 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

    Untuk mengetahui informasi lebih lanjut tentang perintah untuk membuat instance dari command line, baca dokumentasi gcloud CLI.

    Vertex AI Workbench membuat sebuah instance dan otomatis memulainya. Saat instance siap digunakan, Vertex AI Workbench akan mengaktifkan link Open JupyterLab di konsol Google Cloud .

    Opsi konfigurasi jaringan

    Selain opsi jaringan umum, instance Vertex AI Workbench dengan container kustom harus memiliki akses ke layanan Artifact Registry.

    Jika Anda telah menonaktifkan akses IP publik untuk VPC, pastikan Anda telah mengaktifkan Akses Google Pribadi.

    Mengaktifkan streaming Image

    Host container kustom disediakan untuk berinteraksi dengan streaming Image di Google Kubernetes Engine (GKE), yang menarik container lebih cepat dan mengurangi waktu inisialisasi untuk container besar setelah di-cache di sistem file jarak jauh GKE.

    Untuk melihat persyaratan untuk mengaktifkan Streaming gambar, lihat Persyaratan. Sering kali, streaming Gambar dapat digunakan dengan instance Vertex AI Workbench dengan mengaktifkan Container File System API.

    Aktifkan Container File System API

    Cara VM host menjalankan container kustom

    Alih-alih menggunakan Docker untuk menjalankan container kustom, VM host menggunakan nerdctl di bawah namespace Kubernetes untuk memuat dan menjalankan container. Hal ini memungkinkan Vertex AI Workbench menggunakan Streaming gambar untuk container kustom.

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

    Contoh penginstalan: container kustom dengan kernel default kustom

    Contoh berikut menunjukkan cara membuat kernel baru dengan paket pip yang telah diinstal sebelumnya.

    1. Buat penampung kustom baru:

      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. Tambahkan penampung baru ke 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. Buat instance:

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

    Kernel persisten untuk container kustom

    Container kustom Vertex AI Workbench hanya memasang disk data ke direktori /home/USER dalam setiap container, dengan jupyter adalah pengguna default. Artinya, setiap perubahan di luar /home/USER bersifat sementara dan tidak akan tetap ada setelah dimulai ulang. Jika Anda ingin paket yang diinstal tetap ada untuk kernel tertentu, Anda dapat membuat kernel di direktori /home/USER.

    Untuk membuat kernel di direktori /home/USER:

    1. Buat lingkungan 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"

      Ganti kode berikut:

      • USER: nama direktori pengguna, yang secara default adalah jupyter
      • ENVIRONMENT_NAME: nama lingkungan
      • PYTHON_VERSION: versi Python, misalnya 3.11

    2. Tunggu 30 detik hingga 1 menit agar kernel dimuat ulang.

    Memperbarui startup container dasar

    Container dasar untuk instance Vertex AI Workbench (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) memulai JupyterLab dengan menjalankan /run_jupyter.sh.

    Jika Anda mengubah startup container dalam container turunan, Anda harus menambahkan /run_jupyter.sh untuk menjalankan konfigurasi default JupyterLab.

    Berikut adalah contoh cara Dockerfile dapat diubah:

    # 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

    Memperbarui Konfigurasi JupyterLab dalam container dasar

    Jika Anda perlu mengubah konfigurasi JupyterLab di penampung dasar, Anda harus melakukan hal berikut:

    • Pastikan JupyterLab dikonfigurasi ke port 8080. Agen proxy kami dikonfigurasi untuk meneruskan permintaan apa pun ke port 8080 dan jika server jupyter tidak memproses port yang benar, instance akan mengalami masalah penyediaan.

    • Ubah paket JupyterLab di lingkungan jupyterlab micromamba. Kami menyediakan lingkungan paket terpisah untuk menjalankan JupyterLab dan pluginnya guna memastikan tidak ada konflik dependensi dengan lingkungan kernel. Jika Anda ingin menginstal ekstensi JupyterLab tambahan, Anda harus menginstalnya dalam lingkungan jupyterlab. Contoh:

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

    Metadata Container Kustom

    Selain daftar metadata standar yang dapat diterapkan ke instance Vertex AI Workbench, instance dengan container kustom mencakup metadata berikut untuk mengelola instansiasi container payload:

    Fitur Deskripsi Kunci metadata Nilai dan default yang diterima
    Mengaktifkan Cloud Storage FUSE pada image container

    Memasang /dev/fuse ke container dan mengaktifkan gcsfuse untuk digunakan di container.

    		container-allow-fuse
    • true: Mengaktifkan Cloud Storage FUSE.
    • false (default): Tidak mengaktifkan Cloud Storage FUSE.
    Parameter tambahan untuk menjalankan penampung

    Menambahkan parameter penampung tambahan ke nerdctl run, dengan nerdctl adalah Containerd CLI.

    		container-custom-params

    String parameter eksekusi container. Contoh: --v /mnt/disk1:/mnt/disk1.

    Flag lingkungan penampung tambahan

    Menyimpan variabel Lingkungan ke dalam tanda di bagian /mnt/stateful_partition/workbench/container_env dan menambahkannya ke nerdctl run.

    		container-env-file

    String variabel lingkungan container. Contoh: CONTAINER_NAME=derivative-container.

    Mengupgrade Container Kustom

    Saat instance Anda dimulai untuk pertama kalinya, instance akan menarik image container dari URI yang disimpan dalam metadata custom-container-payload. Jika Anda menggunakan tag :latest, container akan diperbarui setiap kali dimulai ulang. Nilai metadata custom-container-payload tidak dapat diubah secara langsung karena merupakan kunci metadata yang dilindungi.

    Untuk mengupdate image container kustom instance, Anda dapat menggunakan metode berikut yang didukung oleh Google Cloud CLI, Terraform, atau Notebooks API.

    gcloud

    Anda dapat memperbarui metadata image container kustom pada instance Vertex AI Workbench menggunakan perintah berikut:

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

    Terraform

    Anda dapat mengubah kolom container_image dalam konfigurasi terraform untuk memperbarui payload penampung.

    Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar 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

    Gunakan metode instances.patch dengan perubahan pada gce_setup.container_image.repository dan gce_setup.container_image.tag di updateMask.

    Menjalankan alat diagnostik

    Alat diagnostik memeriksa dan memverifikasi status berbagai layanan Vertex AI Workbench. Untuk mempelajari lebih lanjut, lihat Tugas yang dilakukan oleh alat diagnostik.

    Saat Anda membuat instance Vertex AI Workbench menggunakan container kustom, alat diagnostik tidak tersedia sebagai skrip di lingkungan host yang dapat dijalankan pengguna. Sebagai gantinya, kode ini dikompilasi menjadi biner dan dimuat ke penampung runtime Google yang dibuat untuk menjalankan layanan diagnostik di lingkungan Container-Optimized OS. Lihat Ringkasan Container-Optimized OS.

    Untuk menjalankan alat diagnostik, selesaikan langkah-langkah berikut:

    1. Gunakan ssh untuk terhubung ke instance Vertex AI Workbench.

    2. Di terminal SSH, jalankan perintah berikut:

      sudo docker exec diagnostic-service ./diagnostic_tool

    3. Untuk melihat opsi perintah tambahan, jalankan perintah berikut:

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

    Untuk mengetahui informasi selengkapnya tentang opsi alat diagnostik, lihat dokumentasi pemantauan status kondisi.

    Untuk menjalankan alat diagnostik menggunakan REST API, lihat dokumentasi REST API.

    Mengakses instance Anda

    Anda dapat mengakses instance melalui URL proxy.

    Setelah instance dibuat dan aktif, Anda dapat memperoleh URL proxy menggunakan gcloud CLI.

    Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

    • INSTANCE_NAME: nama instance Vertex AI Workbench Anda
    • PROJECT_ID: project ID Anda
    • LOCATION adalah zona tempat instance Anda berada.

    Jalankan perintah berikut:

    Linux, macOS, atau 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

    Perintah describe akan menampilkan URL proxy Anda. Untuk mengakses instance, buka URL proxy di browser web.

    Untuk mengetahui informasi selengkapnya tentang perintah untuk mendeskripsikan instance dari command line, lihat dokumentasi gcloud CLI.