Create an instance using a custom container

Create an instance using a custom container

This page describes how to create a Vertex AI Workbench instance based on a custom container.

Overview

Vertex AI Workbench instances support using a custom container derived from a Google-provided base container. You can modify this base container to make a custom container image and use this custom container to create a Vertex AI Workbench instance.

The base container is configured with a Container-Optimized OS in the host virtual machine (VM). The base container provides pre-installed data science packages and specific configurations that enable your instance to integrate with Google Cloud.

The base container is located at gcr.io/deeplearning-platform-release/workbench-container:latest.

Limitations

Consider the following limitations when planning your project:

• The custom container must be derived from the Google-provided base container (gcr.io/deeplearning-platform-release/workbench-container:latest). Using a container that isn't derived from the base container isn't supported and increases the risks of compatibility issues with our services.

• Use of more than one container with a Vertex AI Workbench instance isn't supported.

• Supported metadata for custom containers from user-managed notebooks and managed notebooks can have different behavior when used with Vertex AI Workbench instances.

Before you begin

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

Required roles

To ensure that your user account has the necessary permissions to create a Vertex AI Workbench instance, ask your administrator to grant your user account the Notebooks Runner (roles/notebooks.runner) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give your user account the required permissions through custom roles or other predefined roles.

Create a custom container

To create a custom container for use with Vertex AI Workbench instances:

1. Create a derivative container derived from the Google-provided base container image (gcr.io/deeplearning-platform-release/workbench-container:latest).

2. Build and push the container to Artifact Registry. You'll use the container's URI when you create your Vertex AI Workbench instance. For example, the URI might look like this: gcr.io/PROJECT_ID/IMAGE_NAME.

Create the instance

You can create a Vertex AI Workbench instance based on a custom container by using the Google Cloud console or the Google Cloud CLI.

Console

To create a Vertex AI Workbench instance based on a custom container, do the following:

1. In the Google Cloud console, go to the Instances page.

   Go to Instances

2. Click  Create new.

3. In the New instance dialog, click Advanced options.

4. In the Create instance dialog, in the Environment section, select Use custom container.

5. For Docker container image, click Select.

6. In the Select container image dialog, navigate to the container image that you want to use, and then click Select.

7. Optional. For Post-startup script, enter a path to a post-startup script that you want to use.

8. Complete the rest of the instance creation dialog, and then click Create.

   Vertex AI Workbench creates an instance and automatically starts it. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

gcloud

Before using any of the command data below, make the following replacements:

• INSTANCE_NAME: the name of your Vertex AI Workbench instance; must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen
• PROJECT_ID: your project ID
• LOCATION: the zone where you want your instance to be located
• CUSTOM_CONTAINER_PATH: the path to the container image repository, for example: gcr.io/PROJECT_ID/IMAGE_NAME
• METADATA: custom metadata to apply to this instance; for example, to specify a post-startup-script, you can use the post-startup-script metadata tag, in the format: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and 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)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and 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)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and 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

For more information about the command for creating an instance from the command line, see the gcloud CLI documentation.

Vertex AI Workbench creates an instance and automatically starts it. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link in the Google Cloud console.

Example installation: custom container with a custom default kernel

The following example shows how to create a new kernel with a pip package pre-installed.

1. Create a new custom container:

   FROM gcr.io/deeplearning-platform-release/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. Add the new container to 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. Create an 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
   

Run the diagnostic tool

The diagnostic tool checks and verifies the status of various Vertex AI Workbench services. To learn more, see Tasks performed by the diagnostic tool.

When you create a Vertex AI Workbench instance using a custom container, the diagnostic tool isn't available as a script in the host environment that users can run. Instead, it is compiled into a binary and loaded onto a Google runtime container that is built to run diagnostic services in a Container-Optimized OS environment. See Container-Optimized OS Overview.

To run the diagnostic tool, complete the following steps:

1. Use ssh to connect to your Vertex AI Workbench instance.

2. In the SSH terminal, run the following command:

   sudo docker exec diagnostic-service ./diagnostic_tool
   

3. To view additional command options, run the following command:

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

For more information about the diagnostic tool's options, see the monitoring health status documentation.

To run the diagnostic tool by using the REST API, see the REST API documentation.

Access your instance

You can access your instance through a proxy URL.

After your instance has been created and is active, you can get the proxy URL by using the gcloud CLI.

Before using any of the command data below, make the following replacements:

• INSTANCE_NAME: the name of your Vertex AI Workbench instance
• PROJECT_ID: your project ID
• LOCATION: the zone where your instance is located

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and 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

The describe command returns your proxy URL. To access your instance, open the proxy URL in a web browser.

For more information about the command for describing an instance from the command line, see the gcloud CLI documentation.