Esta página se ha traducido con Cloud Translation API.

Crear una instancia con un contenedor personalizado

En esta página se describe cómo crear una instancia de Vertex AI Workbench basada en un contenedor personalizado.

Información general

Las instancias de Vertex AI Workbench admiten el uso de un contenedor personalizado derivado de uno de los contenedores base proporcionados por Google. Puedes modificar estos contenedores base para crear una imagen de contenedor personalizada y usar estos contenedores personalizados para crear una instancia de Vertex AI Workbench.

Los contenedores base se configuran con un SO optimizado para contenedores en la máquina virtual (VM) host. La imagen de host se crea a partir de la cos-stable familia de imágenes.

Limitaciones

Ten en cuenta las siguientes limitaciones al planificar tu proyecto:

El contenedor personalizado debe derivarse de un contenedor base proporcionado por Google. Si usas un contenedor que no se deriva de un contenedor base, aumenta el riesgo de que surjan problemas de compatibilidad y se limita nuestra capacidad para ofrecerte asistencia con el uso de instancias de Vertex AI Workbench.
No se admite el uso de más de un contenedor con una instancia de Vertex AI Workbench.
Los metadatos admitidos para los contenedores personalizados de los cuadernos gestionados por el usuario y los cuadernos gestionados pueden tener un comportamiento diferente cuando se usan con instancias de Vertex AI Workbench.
La máquina virtual que aloja el contenedor personalizado se ejecuta en un sistema operativo optimizado para contenedores, lo que restringe la forma en que puedes interactuar con la máquina host. Por ejemplo, Container-Optimized OS no incluye un gestor de paquetes. Esto significa que los paquetes que actúan en el host deben ejecutarse en un contenedor con montajes. Esto afecta a las secuencias de comandos posteriores al inicio que se migran desde instancias de cuadernos gestionados e instancias de cuadernos gestionados por el usuario, en las que la máquina host contiene muchas más herramientas que Container-Optimized OS.
Las instancias de Vertex AI Workbench usan nerdctl (una CLI de containerd) para ejecutar el contenedor personalizado. Es necesario para que sea compatible con el servicio de streaming de imágenes. Los parámetros de contenedor que se añadan mediante un valor de metadatos deben cumplir los requisitos de nerdctl.
Las instancias de Vertex AI Workbench se configuran para extraer datos de Artifact Registry o de un repositorio de contenedores público. Para configurar una instancia de forma que extraiga datos de un repositorio privado, debes configurar manualmente las credenciales que usa containerd.

Contenedores base

Contenedor base estándar

El contenedor base estándar es compatible con todas las funciones de Vertex AI Workbench e incluye lo siguiente:

Paquetes de ciencia de datos preinstalados.
Bibliotecas de Cuda similares a los contenedores de aprendizaje profundo.
Google Cloud Integraciones de JupyterLab, como las de Dataproc y BigQuery.
Paquetes de sistema habituales, como curl o git.
Configuración de JupyterLab basada en metadatos.
Gestión de kernels basada en micromamba.

Especificaciones

El contenedor base estándar tiene las siguientes especificaciones:

Imagen base: nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
Tamaño de la imagen: aproximadamente 22 GB
URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

Contenedor de base fina

El contenedor base reducido proporciona un conjunto mínimo de configuraciones que permiten una conexión proxy a la instancia. Las funciones y los paquetes estándar de Vertex AI Workbench no se incluyen, excepto los siguientes:

JupyterLab
Configuración de JupyterLab basada en metadatos
Gestión de kernels basada en micromamba

Los paquetes o las extensiones de JupyterLab adicionales se deben instalar y gestionar por separado.

Especificaciones

El contenedor base reducido tiene las siguientes especificaciones:

Imagen base: marketplace.gcr.io/google/ubuntu24.04
Tamaño de la imagen: aproximadamente 2 GB
URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

Antes de empezar

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

Roles obligatorios

Para obtener los permisos que necesitas para crear una instancia de Vertex AI Workbench con un contenedor personalizado, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

Ejecutor de cuadernos (roles/notebooks.runner) en la cuenta de usuario
Para extraer imágenes del repositorio de Artifact Registry, haz lo siguiente: Lector de Artifact Registry (roles/artifactregistry.reader) en la cuenta de servicio

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Crear un contenedor personalizado

Para crear un contenedor personalizado que se pueda usar con instancias de Vertex AI Workbench, sigue estos pasos:

Crea un contenedor derivado a partir de una imagen de contenedor base proporcionada por Google.
Crea el contenedor y envíalo a Artifact Registry. Usarás el URI del contenedor al crear tu instancia de Vertex AI Workbench. Por ejemplo, el URI podría tener este aspecto: gcr.io/PROJECT_ID/IMAGE_NAME.

Crear la instancia

Puedes crear una instancia de Vertex AI Workbench basada en un contenedor personalizado mediante la Google Cloud consola o la CLI de Google Cloud.

Consola

Para crear una instancia de Vertex AI Workbench basada en un contenedor personalizado, sigue estos pasos:

En la consola, ve a la página Instancias. Google Cloud

Ir a Instancias
Haz clic en Crear.
En el cuadro de diálogo Nueva instancia, haz clic en Opciones avanzadas.
En el cuadro de diálogo Crear instancia, en la sección Entorno, selecciona Usar contenedor personalizado.
En Imagen de contenedor Docker, haz clic en Seleccionar.
En el cuadro de diálogo Seleccionar imagen de contenedor, vaya a la imagen de contenedor que quiera usar y, a continuación, haga clic en Seleccionar.
Opcional. En Secuencia de comandos tras el inicio, introduce la ruta de la secuencia de comandos tras el inicio que quieras usar.
Opcional. Añade metadatos a tu instancia. Para obtener más información, consulta Metadatos de contenedores personalizados.
Opcional. En la sección Redes, personaliza la configuración de tu red. Para obtener más información, consulta Opciones de configuración de red.
Completa el resto del cuadro de diálogo de creación de la instancia y, a continuación, haz clic en Crear.

Vertex AI Workbench crea una instancia y la inicia automáticamente. Cuando la instancia esté lista para usarse, Vertex AI Workbench activará el enlace Abrir JupyterLab.

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

INSTANCE_NAME: el nombre de tu instancia de Vertex AI Workbench. Debe empezar por una letra seguida de un máximo de 62 letras minúsculas, números o guiones (-), y no puede acabar en guion.
PROJECT_ID: tu ID de proyecto
LOCATION: la zona en la que quieres que se encuentre tu instancia
CUSTOM_CONTAINER_PATH: la ruta al repositorio de imágenes del contenedor. Por ejemplo: gcr.io/PROJECT_ID/IMAGE_NAME
METADATA: metadatos personalizados que se aplicarán a esta instancia. Por ejemplo, para especificar un script posterior al inicio, puedes usar la etiqueta de metadatos post-startup-script con el siguiente formato: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Ejecuta el siguiente comando:

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

Para obtener más información sobre el comando para crear una instancia desde la línea de comandos, consulta la documentación de la CLI de gcloud.

Vertex AI Workbench crea una instancia y la inicia automáticamente. Cuando la instancia esté lista para usarse, Vertex AI Workbench activará un enlace Abrir JupyterLab en la consola. Google Cloud

Opciones de configuración de red

Además de las opciones de red generales, una instancia de Vertex AI Workbench con un contenedor personalizado debe tener acceso al servicio Artifact Registry.

Si has desactivado el acceso a la IP pública de tu VPC, asegúrate de que la función Acceso privado de Google esté habilitada.

Habilitar la transmisión de imágenes

El host de contenedor personalizado se aprovisiona para interactuar con la transmisión de imágenes en Google Kubernetes Engine (GKE), que extrae contenedores más rápido y reduce el tiempo de inicialización de los contenedores grandes una vez que se almacenan en caché en el sistema de archivos remoto de GKE.

Para ver los requisitos para habilitar la transmisión de imágenes, consulta la sección Requisitos. A menudo, el streaming de imágenes se puede usar con instancias de Vertex AI Workbench habilitando la API Container File System.

Habilitar la API Container File System

Cómo ejecuta la VM host el contenedor personalizado

En lugar de usar Docker para ejecutar el contenedor personalizado, la VM host usa nerdctl en el espacio de nombres de Kubernetes para cargar y ejecutar el contenedor. De esta forma, Vertex AI Workbench puede usar el streaming de imágenes para contenedores personalizados.

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

Ejemplo de instalación: contenedor personalizado con un kernel predeterminado personalizado

En el siguiente ejemplo se muestra cómo crear un nuevo kernel con un paquete pip preinstalado.

Crea un contenedor personalizado:

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"

Añade el nuevo contenedor a 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

Crea una instancia:

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

Kernels persistentes para contenedores personalizados

Los contenedores personalizados de Vertex AI Workbench solo montan un disco de datos en el directorio /home/USER de cada contenedor, donde jupyter es el usuario predeterminado. Esto significa que cualquier cambio que se haga fuera de /home/USER es efímero y no se conservará después de reiniciar. Si necesitas que los paquetes instalados se conserven en un kernel específico, puedes crear un kernel en el directorio /home/USER.

Para crear un kernel en el directorio /home/USER, sigue estos pasos:

Crea un entorno de 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"

Haz los cambios siguientes:

USER: nombre del directorio de usuarios, que es jupyter de forma predeterminada
ENVIRONMENT_NAME: el nombre del entorno
PYTHON_VERSION: la versión de Python, por ejemplo, 3.11

Espera entre 30 segundos y 1 minuto a que se actualicen los kernels.

Actualizar el inicio del contenedor base

El contenedor base de una instancia de Vertex AI Workbench (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) inicia JupyterLab ejecutando /run_jupyter.sh.

Si modificas el inicio del contenedor en un contenedor derivado, debes añadir /run_jupyter.sh para ejecutar la configuración predeterminada de JupyterLab.

A continuación, se muestra un ejemplo de cómo se puede modificar el archivo 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

Actualizar la configuración de JupyterLab en el contenedor base

Si necesitas modificar la configuración de JupyterLab en el contenedor base, debes hacer lo siguiente:

Asegúrate de que JupyterLab esté configurado en el puerto 8080. Nuestro agente proxy está configurado para reenviar cualquier solicitud al puerto 8080. Si el servidor Jupyter no está escuchando el puerto correcto, la instancia tendrá problemas de aprovisionamiento.
Modifica los paquetes de JupyterLab en el entorno jupyterlab micromamba. Proporcionamos un entorno de paquetes independiente para ejecutar JupyterLab y su complemento, de modo que no haya conflictos de dependencias con el entorno del kernel. Si quieres instalar una extensión de JupyterLab adicional, debes hacerlo en el entorno jupyterlab. Por ejemplo:
```
# DockerFile
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
RUN micromamba activate jupyterlab && \
  jupyter nbextension install nbdime
```

Metadatos de contenedor personalizado

Además de la lista estándar de metadatos que se pueden aplicar a una instancia de Vertex AI Workbench, las instancias con contenedores personalizados incluyen los siguientes metadatos para gestionar la instanciación del contenedor de carga útil:

Función	Descripción	Clave de metadatos	Valores aceptados y predeterminados
Habilita Cloud Storage FUSE en una imagen de contenedor.	Monta `/dev/fuse` en el contenedor y habilita `gcsfuse` para usarlo en el contenedor.	`container-allow-fuse`	`true`: habilita Cloud Storage FUSE. `false` (predeterminado): no habilita Cloud Storage FUSE.
Parámetros de ejecución de contenedores adicionales	Añade parámetros de contenedor adicionales a `nerdctl run`, donde `nerdctl` es la CLI de Containerd.	`container-custom-params`	Una cadena de parámetros de ejecución de contenedores. Ejemplo: `--v /mnt/disk1:/mnt/disk1`.
Marcas de entorno de contenedor adicionales	Almacena las variables de entorno en un elemento de configuración bajo `/mnt/stateful_partition/workbench/container_env` y lo añade a `nerdctl run`.	`container-env-file`	Cadena de variables de entorno del contenedor. Ejemplo: `CONTAINER_NAME=derivative-container`.

Actualizar un contenedor personalizado

Cuando la instancia se inicia por primera vez, extrae la imagen del contenedor de un URI almacenado en los custom-container-payloadmetadatos. Si usas la etiqueta :latest, el contenedor se actualiza cada vez que se reinicia. El valor de metadatos custom-container-payload no se puede modificar directamente porque es una clave de metadatos protegida.

Para actualizar la imagen de contenedor personalizada de tu instancia, puedes usar los siguientes métodos compatibles con la CLI de Google Cloud, Terraform o la API Notebooks.

gcloud

Para actualizar los metadatos de la imagen de contenedor personalizada en una instancia de Vertex AI Workbench, usa el siguiente comando:

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

Terraform

Puedes cambiar el campo container_image en la configuración de Terraform para actualizar la carga útil del contenedor.

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de 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"
    }
  }
}

API de Notebooks

Usa el método instances.patch con los cambios en gce_setup.container_image.repository y gce_setup.container_image.tag en updateMask.

Ejecutar la herramienta de diagnóstico

La herramienta de diagnóstico comprueba y verifica el estado de varios servicios de Vertex AI Workbench. Para obtener más información, consulta Tareas realizadas por la herramienta de diagnóstico.

Cuando creas una instancia de Vertex AI Workbench con un contenedor personalizado, la herramienta de diagnóstico no está disponible como secuencia de comandos en el entorno host que los usuarios pueden ejecutar. En su lugar, se compila en un archivo binario y se carga en un contenedor de tiempo de ejecución de Google diseñado para ejecutar servicios de diagnóstico en un entorno de Container-Optimized OS. Consulta la información general de Container-Optimized OS.

Para ejecutar la herramienta de diagnóstico, sigue estos pasos:

Usa SSH para conectarte a tu instancia de Vertex AI Workbench.

En el terminal SSH, ejecuta el siguiente comando:

sudo docker exec diagnostic-service ./diagnostic_tool

Para ver más opciones de comandos, ejecuta el siguiente comando:

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

Para obtener más información sobre las opciones de la herramienta de diagnóstico, consulta la documentación sobre el estado de salud de la monitorización.

Para ejecutar la herramienta de diagnóstico mediante la API REST, consulta la documentación de la API REST.

Acceder a tu instancia

Puedes acceder a tu instancia a través de una URL de proxy.

Una vez que se haya creado la instancia y esté activa, puedes obtener la URL del proxy mediante la CLI de gcloud.

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

INSTANCE_NAME: el nombre de tu instancia de Vertex AI Workbench
PROJECT_ID: tu ID de proyecto
LOCATION: la zona en la que se encuentra tu instancia

Ejecuta el siguiente comando:

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

El comando describe devuelve la URL de tu proxy. Para acceder a tu instancia, abre la URL del proxy en un navegador web.

Para obtener más información sobre el comando para describir una instancia desde la línea de comandos, consulta la documentación de la CLI de gcloud.