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:

    • PROJECT_ID: Your project ID
    • ZONE: The Google Cloud zone where your instance is located
    • INSTANCE_NAME: The name of your instance
  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 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, Notebooks 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 running JupyterLab notebooks.

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

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

By default, when you use Notebooks to create a JupyterLab instance, the proxy-mode metadata setting is added automatically, but if you change or remove that setting then the Notebooks instance will no longer be able to connect to the proxy service.

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

  1. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  2. In the Instance name column, click the Notebooks 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 Notebooks instance. If possible, you might want to work with your network and firewall administrators to allow access to your Notebooks instance through the public internet.

Your Notebooks instance does not have an external IP address

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

  1. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  2. In the Instance name column, click the Notebooks 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 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 Notebooks instance is unable to register with the proxy service.

To access these logs, complete the following steps:

  1. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  2. Click the name of the Notebooks instance you want to troubleshoot.

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

What's next

See Troubleshooting notebooks for tips on resolving other issues.