Crea una instancia con un contenedor personalizado

Crea 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.

Descripción general

Se admiten instancias de Vertex AI Workbench con un contenedor personalizado derivado de un contenedor base proporcionado por Google. Puedes modificar este contenedor base a fin de crear una imagen de contenedor personalizada y usar este contenedor personalizado para crear una instancia de Vertex AI Workbench.

El contenedor base se configura con Container-Optimized OS en la máquina virtual (VM) host. El contenedor base proporciona paquetes de ciencia de datos preinstalados y configuraciones específicas que permiten que tu instancia se integre con Google Cloud.

El contenedor base se encuentra engcr.io/deeplearning-platform-release/workbench-container:latest.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando planifiques tu proyecto:

• El contenedor personalizado debe derivar del contenedor base proporcionado por Google (gcr.io/deeplearning-platform-release/workbench-container:latest). El uso de un contenedor que no deriva del contenedor base aumenta el riesgo de problemas de compatibilidad y limita nuestra capacidad para admitir el uso de instancias de Vertex AI Workbench.

• El uso de más de un contenedor con una instancia de Vertex AI Workbench no es compatible.

• Los metadatos admitidos para contenedores personalizados de notebooks administrados por el usuario y notebooks administrados pueden tener un comportamiento diferente cuando se usan con instancias de Vertex AI Workbench.

• La VM que aloja el contenedor personalizado se ejecuta desde un SO optimizado para contenedores, lo que restringe la forma en que puedes interactuar con la máquina anfitrión. Por ejemplo, Container-Optimized OS no incluye un administrador de paquetes. Esto significa que los paquetes que actúan en el host deben realizarse en un contenedor con activaciones. Esto afecta a las secuencias de comandos posteriores al inicio que se migran desde instancias de notebooks administradas y de notebooks administradas por el usuario, en las que la máquina anfitrión 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. Esto es obligatorio para la compatibilidad con el servicio de transmisión de imágenes. Cualquier parámetro de contenedor que se agregue con un valor de metadatos debe cumplir con lo que admite nerdctl.

• Las instancias de Vertex AI Workbench están configuradas para extraer desde Artifact Registry o un repositorio de contenedores público. Para configurar una instancia para que extraiga de un repositorio privado, debes configurar manualmente las credenciales que usa containerd.

Antes de comenzar

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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

Roles obligatorios

Para obtener los permisos que necesitas para crear una instancia de Vertex AI Workbench con un contenedor personalizado, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Ejecutor de notebooks (roles/notebooks.runner) en la cuenta de usuario
• Para extraer imágenes del repositorio de Artifact Registry, debes tener el rol de lector de Artifact Registry (roles/artifactregistry.reader) en la cuenta de servicio.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crea un contenedor personalizado

Para crear un contenedor personalizado para usarlo con instancias de Vertex AI Workbench, sigue estos pasos:

1. Crea un contenedor derivado de la imagen del contenedor base proporcionado por Google (gcr.io/deeplearning-platform-release/workbench-container:latest).

2. Compila y envía el contenedor a Artifact Registry. Usarás el URI del contenedor cuando crees tu instancia de Vertex AI Workbench. Por ejemplo, el URI podría verse así: gcr.io/PROJECT_ID/IMAGE_NAME.

Crea la instancia

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

Console

Para crear una instancia de Vertex AI Workbench basada en un contenedor personalizado, haz lo siguiente:

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

   Ir a Instancias

2. Haz clic en  Crear nuevo.

3. En el cuadro de diálogo Instancia nueva, haz clic en Opciones avanzadas.

4. En el diálogo Crear instancia, en la sección Entorno, selecciona Usar contenedor personalizado.

5. En Imagen de contenedor de Docker, haz clic en Seleccionar.

6. En el cuadro de diálogo Seleccionar imagen de contenedor, navega a la imagen de contenedor que deseas usar y haz clic en Seleccionar.

7. Opcional. En Secuencia de comandos posterior al inicio, ingresa una ruta de acceso a la secuencia de comandos posterior al inicio que deseas usar.

8. Opcional. Agrega metadatos para tu instancia. Para obtener más información, consulta Metadatos de contenedores personalizados.

9. Opcional. En la sección Herramientas de redes, personaliza la configuración de red. Para obtener más información, consulta Opciones de configuración de red.

10. Completa el resto del diálogo de creación de la instancia y, luego, haz clic en Crear.

    Vertex AI Workbench crea una instancia y la inicia de forma automática. Cuando la instancia está lista para usarse, Vertex AI Workbench activa un vínculo Abrir JupyterLab.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

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

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init, o gcloud auth login y gcloud config set project.

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

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

Vertex AI Workbench crea una instancia y la inicia de forma automática. Cuando la instancia está lista para usarse, Vertex AI Workbench activa un vínculo Abrir JupyterLab en la consola de 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 de Artifact Registry.

Si desactivaste el acceso de IP pública para tu VPC, asegúrate de haber habilitado el Acceso privado a Google.

Habilita 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 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 Requisitos. A menudo, se puede usar la transmisión de imágenes con instancias de Vertex AI Workbench si se habilita la API de Container File System.

Habilita la API del sistema de archivos de contenedor

Cómo la VM del host ejecuta 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. Esto permite que Vertex AI Workbench use la transmisión 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 kernel nuevo con un paquete de pip preinstalado.

1. Crea un nuevo 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

2. Agrega el contenedor nuevo 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

3. Cree una instancia

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

Kernels persistentes para contenedores personalizados

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

Para crear un kernel en el directorio /home/USER, haz lo siguiente:

1. Crea un entorno 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. Espera entre 30 segundos y 1 minuto para que se actualicen los kernels.

Actualiza 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 agregar /run_jupyter.sh para ejecutar la configuración predeterminada de JupyterLab.

El siguiente es un ejemplo de cómo se podría modificar el 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

Actualiza la configuración de JupyterLab dentro del 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 de proxy está configurado para reenviar cualquier solicitud al puerto 8080 y, si el servidor de Jupyter no está escuchando el puerto correcto, la instancia tiene problemas de aprovisionamiento.

• Modifica los paquetes de JupyterLab en el entorno micromamba jupyterlab. Proporcionamos un entorno de paquetes independiente para ejecutar JupyterLab y su plugin para garantizar 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 del contenedor personalizado

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

Atributo	Descripción	Clave de metadatos	Valores predeterminados y valores aceptados
Habilita FUSE de Cloud Storage en una imagen de contenedor.	Activa /dev/fuse en el contenedor y habilita gcsfuse para usarlo en el contenedor.	container-allow-fuse	true: Habilita Cloud Storage FUSE. false (predeterminada): No habilita Cloud Storage FUSE.
Parámetros de ejecución de contenedor adicionales	Agrega parámetros de contenedor adicionales a nerdctl run, donde nerdctl es la CLI de Containerd.	container-custom-params	Es una cadena de parámetros de ejecución de contenedores. Ejemplo: --v /mnt/disk1:/mnt/disk1.
Marcas adicionales del entorno de contenedor	Almacena las variables de entorno en una marca en /mnt/stateful_partition/workbench/container_env y la adjunta a nerdctl run.	container-env-file	Es una cadena de variables de entorno del contenedor. Ejemplo: CONTAINER_NAME=derivative-container.
URI del contenedor de la carga útil	La carga útil del contenedor personalizado con JupyterLab que se extrae a la instancia de Vertex AI Workbench.	custom-container-payload	Es una cadena de URI. Ejemplo: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest.

Actualiza un contenedor personalizado

Si tu contenedor personalizado necesita actualizarse, puedes hacerlo actualizando el valor de metadatos custom-container-payload con el URI del contenedor nuevo. Cada reinicio del contenedor intenta extraerlo del URI almacenado en custom-container-payload.

Si usas la etiqueta :latest, el contenedor base se actualiza en cada reinicio. Consulta el siguiente ejemplo:

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

Para evitar actualizar el contenedor base, puedes especificar la versión. Consulta el siguiente ejemplo:

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

Ejecuta la herramienta de diagnóstico

La herramienta de diagnóstico verifica el estado de varios servicios de Vertex AI Workbench. Para obtener más información, consulta Tareas que realiza 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 una secuencia de comandos en el entorno del host que los usuarios pueden ejecutar. En su lugar, se compila en un objeto binario y se carga en un contenedor de entorno de ejecución de Google que se compila para ejecutar servicios de diagnóstico en un entorno de Container-Optimized OS. Consulta la descripción general de Container-Optimized OS.

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

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

2. En la terminal de SSH, ejecuta el siguiente comando:

   sudo docker exec diagnostic-service ./diagnostic_tool

3. Para ver las opciones de comandos adicionales, 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 de supervisión del estado de salud.

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

Accede a tu instancia

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

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

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

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

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

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 muestra la URL del proxy. Para acceder a tu instancia, abre la URL del proxy en un navegador web.

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