Use SSH to access JupyterLab

Vertex AI Workbench user-managed notebooks isdeprecated. On April 14, 2025, support for user-managed notebooks ended and the ability to create user-managed notebooks instances was removed. Existing instances will continue to function until March 30, 2026, but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that youmigrate 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 upSSH port forwarding,complete the following steps, and then access your JupyterLab session through alocal browser:

1. Run the following command by using theGoogle Cloud CLI inyour preferred terminal or inCloud Shell:

   gcloudcomputessh\--projectPROJECT_ID\--zoneZONE\INSTANCE_NAME\---L8080:localhost:8080

   Replace the following:

   • PROJECT_ID: yourGoogle Cloud project ID
   • ZONE: thezonewhere your instance is located
   • INSTANCE_NAME: the name of yourinstance

1. Access your JupyterLab session through a local browser:

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

   • If you ran the command usingCloud Shell,access JupyterLab through the WebPreview on port 8080.

Reasons why you might not have HTTPS access

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

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

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

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

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

• YourVPC Service Controls settingsblock access toArtifact Registry.

The following sections show how to resolve these issues.

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

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

By default, when you use user-managed notebooks to createa JupyterLab instance, Vertex AI Workbench addsthe proxy-mode metadata setting.If you change or remove the proxy-mode metadata setting, thenthe user-managed notebooks instancecan't connect to the proxy service.

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

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

   Go to User-managed notebooks

2. Select the instance that you need to modify.

3. Next toView VM details, clickView in Compute Engine.

4. On the VM details page, clickEdit.

5. In theMetadata section, add or modifythe metadata to ensure there is aproxy-mode entrysetto the correct value, for example:project_editors`.

   Learn more about the possible values of theproxy-mode metadataentry.

6. ClickSave.

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 internetor your firewall rules block egress traffic, you must use SSH to accessyour user-managed notebooks instance.If possible, you might want to workwith your network and firewall administrators to allow access to youruser-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 instancewithout anexternal IP address. If you need to change this, complete the followingsteps.

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

   Go to User-managed notebooks

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

3. ClickView VM details.

4. ClickEdit.

5. In theNetwork interfaces section, expand the network thatyou want to have an external IP address.

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

7. In theNetwork interfaces section, clickDone.

8. ClickSave.

VPC Service Controls settings are blocking access to Artifact Registry

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

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

Further troubleshooting

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

To access these logs, complete the following steps:

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

   Go to User-managed notebooks

2. Select the instance that you want to troubleshoot.

3. InLogs, clickSerial port 1 (console).

What's next

For tips on resolving other issues,see thetroubleshooting section on user-managednotebooks.