Crea una instancia con un contenedor personalizado

En esta página, se describe cómo crear una instancia de Gemini Enterprise Agent Platform Workbench basada en un contenedor personalizado.

Descripción general

Las instancias de Agent Platform 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 Agent Platform Workbench.

Los contenedores base se configuran con un Container-Optimized OS en la máquina virtual (VM) host. La imagen del host se compila a partir de la cos-stable familia de imágenes.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando planifiques tu proyecto:

  • El contenedor personalizado debe derivar de un contenedor base proporcionado por Google. El uso de un contenedor que no deriva de un contenedor base aumenta el riesgo de problemas de compatibilidad y limita nuestra capacidad para brindar asistencia en el uso de instancias de Agent Platform Workbench.

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

  • La VM que aloja el contenedor personalizado se ejecuta en un Container-Optimized OS, 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 se deben ejecutar en un contenedor con puntos de montaje.

  • Las instancias de Agent Platform Workbench usan nerdctl (una CLI de containerd) para ejecutar el contenedor personalizado. Esto es necesario para la compatibilidad con el servicio de transmisión de imágenes. Todos los parámetros del contenedor que se agreguen con un valor de metadatos deben cumplir con lo que admite nerdctl.

  • Las instancias de Agent Platform Workbench están configuradas para extraer datos de Artifact Registry o de un repositorio de contenedores público. Para configurar una instancia para 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 admite todas las funciones de Agent Platform Workbench y, además, incluye lo siguiente:

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 base delgado

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

  • JupyterLab
  • Configuración de JupyterLab basada en metadatos
  • Administración de kernels basada en Micromamba

Los paquetes adicionales o las extensiones de JupyterLab se deben instalar y administrar de forma independiente.

Especificaciones

El contenedor base delgado 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 comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

  5. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

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

    8.

Roles obligatorios

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

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 a través de roles personalizados o cualquier otro rol predefinido.

Crea un contenedor personalizado

Para crear un contenedor personalizado para usarlo con instancias de Agent Platform Workbench, haz lo siguiente:

  1. Crea un contenedor derivado de una imagen de contenedor base proporcionada por Google.

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

Crea la instancia

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

Console

Para crear una instancia de Agent Platform 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 del contenedor de Docker, haz clic en Seleccionar.

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

  7. Es opcional. En Secuencia de comandos posterior al inicio, ingresa la ruta de acceso a una secuencia de comandos posterior al inicio que desees usar.

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

  9. Es opcional. En la sección 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.

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

gcloud

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

  • INSTANCE_NAME: el nombre de tu instancia de Agent Platform 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: Es el ID del 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

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

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.

Agent Platform Workbench crea una instancia y la inicia de forma automática. Cuando la instancia está lista para usarse, Agent Platform Workbench activa un vínculo Abrir JupyterLab en la Google Cloud consola.

Opciones de configuración de red

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

Si desactivaste el acceso a la 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 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 Requisitos. A menudo, la transmisión de imágenes se puede usar con instancias de Agent Platform 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 Agent Platform 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 contenedor personalizado nuevo:

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

  3. Cree 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 Agent Platform 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 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"

    Reemplaza lo siguiente:

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

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

Actualiza el inicio del contenedor básico

El contenedor base para una instancia de Agent Platform 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.

A continuación, se muestra 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

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

Actualiza 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 para 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 en el puerto correcto, la instancia tendrá problemas de aprovisionamiento.

  • Modifica los paquetes de JupyterLab en el entorno de jupyterlab micromamba. Proporcionamos un entorno de paquetes separado para ejecutar JupyterLab y su complemento, de modo que no haya conflictos de dependencias con el entorno del kernel. Si deseas instalar una extensión adicional de JupyterLab, 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 pueden aplicar a una instancia de la plataforma de agentes de Gemini Enterprise Workbench, las instancias con contenedores personalizados incluyen los siguientes metadatos para administrar la creación de instancias del contenedor de carga útil:

Función 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 contenedores 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 del contenedor. Ejemplo: --v /mnt/disk1:/mnt/disk1.

Marcas adicionales del entorno de contenedores

Almacena las variables de entorno en una marca en /mnt/stateful_partition/workbench/container_env y las agrega a nerdctl run.

container-env-file

Es una cadena de variables de entorno del contenedor. Ejemplo: CONTAINER_NAME=derivative-container.

Actualiza un contenedor personalizado

Cuando tu instancia se inicia por primera vez, extrae la imagen de contenedor de un URI almacenado en los metadatos de custom-container-payload. Si usas la etiqueta :latest, el contenedor se actualiza en cada reinicio. 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 Google Cloud CLI, Terraform o la API de Notebooks.

gcloud

Puedes actualizar los metadatos de la imagen de contenedor personalizada en una instancia de Agent Platform Workbench con 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.

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los 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 cambios en gce_setup.container_image.repository y gce_setup.container_image.tag en updateMask.

Ejecuta la herramienta de diagnóstico

La herramienta de diagnóstico verifica el estado de varios servicios de Agent Platform Workbench. Para obtener más información, consulta Tareas que realiza la herramienta de diagnóstico.

Cuando creas una instancia de Agent Platform Workbench con un contenedor personalizado, la herramienta de diagnóstico no está disponible como una secuencia de comandos en el entorno host que los usuarios pueden ejecutar. En cambio, se compila en un objeto binario y se carga en un contenedor de tiempo de ejecución de Google creado 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 Agent Platform Workbench.

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

    sudo docker exec diagnostic-service ./diagnostic_tool

  3. Para ver 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 sobre el monitoreo del estado.

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 Agent Platform Workbench
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: La zona en la que se encuentra la 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 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.