Use SSH to access JupyterLab

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

Follow these steps to set up SSH port forwarding and then access your JupyterLab session through a local browser:

  1. Type the following command in either Cloud Shell or a local environment where the Cloud SDK is installed.

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

    Replace the following:

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

    If using Cloud Shell, access JupyterLab through the Web Preview on port 8080. The Web Preview button Web Preview Button can be found on the top right of the Cloud Shell taskbar.

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

Common reasons why you might not have HTTPS access to JupyterLab include the following:

  • 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 does not have an external IP address.

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

Learn about how to resolve these issues in the following sections.

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, the proxy-mode metadata setting is added automatically. 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 Notebooks page.

    Go to Notebooks

  2. On the User-managed notebooks tab, select the instance that you need to modify.

  3. Click Edit.

  4. Scroll down to the Custom metadata section, and either add or modify the metadata to ensure there is a proxy-mode entry set to the correct value, for example: project_editors.

    Metadata settings with proxy-mode set to project_editors.

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

  5. 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 does not 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 Notebooks page.

    Go to Notebooks

  2. On the User-managed notebooks tab, select the instance that you need to modify.

  3. Click Edit.

  4. Scroll down to the Network interfaces section, and under Network interfaces, click the box to expand it.

  5. Under External IP, click the drop-down menu, select the option that you want, and adjust the other IP address settings to what you want. Note that to resolve this issue, you must not choose None.

    Network interface settings

  6. At the bottom of the Network interfaces box, click Done.

  7. Click Save.

VPC Service Controls settings are blocking access to Container Registry

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

If your VPC Service Controls settings are blocking access to Container Registry, you must add the Container 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 Notebooks page.

    Go to Notebooks

  2. On the User-managed notebooks tab, 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.