Use SSH to access JupyterLab

Use SSH to access JupyterLab

Vertex AI Workbench user-managed notebooks is deprecated. On January 30, 2025, support for user-managed notebooks will end and the ability to create user-managed notebooks instances will be removed. Existing instances will continue to function but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that you migrate your user-managed notebooks instances to Vertex AI Workbench instances.

Whenever you don't have HTTPS access to your JupyterLab instance, you must use SSH to establish a connection.

To set up SSH port forwarding, complete the following steps, and then access your JupyterLab session through a local browser:

1. Run the following command by using the Google Cloud CLI in your preferred terminal or in Cloud Shell:

   gcloud compute ssh \
       --project PROJECT_ID \
       --zone ZONE \
       INSTANCE_NAME \
       -- -L 8080:localhost:8080
   

   Replace the following:

   • PROJECT_ID: your Google Cloud project ID
   • ZONE: the zone where your instance is located
   • INSTANCE_NAME: the name of your instance

Note: If using Cloud Shell to run the command, add a -4 to the SSH flags to use IPv4 to connect. Example: -- -4 -L LOCAL_PORT:localhost:REMOTE_PORT

1. Access your JupyterLab session through a local browser:

   • If you ran the command on your local machine, visit https://localhost:8080 to access JupyterLab.

   • If you ran the command using Cloud Shell, access JupyterLab through the  Web Preview on port 8080.

Reasons why you might not have HTTPS access

To get HTTPS access to JupyterLab, your user-managed notebooks instance must have access to a Google Cloud proxy service. When the instance starts, it attempts to register itself with the proxy service. If it fails to get proxy access, your user-managed notebooks instance prompts you to access JupyterLab through SSH.

The following are common reasons why you might not have HTTPS access to JupyterLab:

• Your JupyterLab instance's proxy-mode metadata setting is incorrect.

• Your network is configured to block internet access for the virtual machines (VMs) running JupyterLab notebooks.

• Your user-managed notebooks instance doesn't have an external IP address.

• Your VPC Service Controls settings block access to Artifact Registry.

The following sections show how to resolve these issues.

For changes to take effect, you might need to restart the notebook's VM when attempting to resolve these issues.

Your JupyterLab instance's proxy-mode metadata setting is incorrect

By default, when you use user-managed notebooks to create a JupyterLab instance, Vertex AI Workbench adds the proxy-mode metadata setting. If you change or remove the proxy-mode metadata setting, then the user-managed notebooks instance can't connect to the proxy service.

To make sure your proxy-mode metadata setting is valid, complete the following steps:

1. In the Google Cloud console, go to the User-managed notebooks page.

   Go to User-managed notebooks

2. Select the instance that you need to modify.

3. Next to View VM details, click View in Compute Engine.

4. On the VM details page, click Edit.

5. In the Metadata section, add or modify the metadata to ensure there is a proxy-mode entryset to the correct value, for example:project_editors`.

   Learn more about the possible values of the proxy-mode metadata entry.

6. Click Save.

The network is blocking internet access

Your JupyterLab instance accesses the proxy service through a public URL. If your Virtual Private Cloud network settings block access to the public internet or your firewall rules block egress traffic, you must use SSH to access your user-managed notebooks instance. If possible, you might want to work with your network and firewall administrators to allow access to your user-managed notebooks instance through the public internet.

Your user-managed notebooks instance doesn't have an external IP address

You might have created your user-managed notebooks instance without an external IP address. If you need to change this, complete the following steps.

1. In the Google Cloud console, go to the User-managed notebooks page.

   Go to User-managed notebooks

2. Click the name of the instance that you need to modify.

3. Click View VM details.

4. Click Edit.

5. In the Network interfaces section, expand the network that you want to have an external IP address.

6. Click the External IP address drop-down menu, and select the option that you want. To resolve this issue, you must not choose None.

7. In the Network interfaces section, click Done.

8. Click Save.

VPC Service Controls settings are blocking access to Artifact Registry

To connect to the proxy service, your user-managed notebooks instance runs an agent that it downloads from Artifact Registry. Without this agent your instance cannot connect to the proxy service.

If your VPC Service Controls settings are blocking access to Artifact Registry, you must add the Artifact Registry service to the service perimeter of your VPC Service Controls. Learn more about how service perimeters work and what services VPC Service Controls can be used to secure.

Further troubleshooting

If you are still having trouble connecting, try reviewing the console logs for your virtual machine. These logs might help you discover why the user-managed notebooks instance is unable to register with the proxy service.

To access these logs, complete the following steps:

1. In the Google Cloud console, go to the User-managed notebooks page.

   Go to User-managed notebooks

2. Select the instance that you want to troubleshoot.

3. In Logs, click Serial port 1 (console).

What's next

For tips on resolving other issues, see the troubleshooting section on user-managed notebooks.