Using VS Code remote ssh settings¶

Using the Remote - Tunnel extension¶

The Remote - Tunnels extension allows you to connect to HPC compute nodes such that higher processing power can be available while still respecting the queuing system resource allocations.

Prerequisites¶

1. Allocate a compute node with salloc to obtain an interactive session.
2. Ensure the code CLI is available on the compute node. - code has been installed in /local/cqls/opt/bin to facilitate this. You can skip this step if running code --version produces a result. code is not supported on ppc64le at this time.

Install the VS Code CLI on the compute node¶

Run the following command on the allocated node to download and extract the VS Code binary:

curl -L 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' | tar xz

This will create a code executable in the current directory.

Start a tunnel¶

After the download finishes, start a tunnel to your local machine:

code tunnel

Follow the prompts to authenticate with your Microsoft account (use your ONID credentials).

Once the tunnel is established, install the Remotes - Tunnels extension if you haven't already, and then authenticate with your ONID credentials in VS Code on your local machine - choose the Microsoft account option - (or the web vscode interface) to connect to the compute node, allowing you to edit files, run terminals, and submit jobs.

Submitting jobs from the tunnel¶

You can use salloc or hqsub as usual within the tunnel session. The VS Code terminal runs on the compute node, so any commands you execute (including salloc, sbatch) will operate on the HPC resources.

Tips¶

• Keep the tunnel session active; closing the terminal will terminate the connection.
• Restarting a code tunnel command on a machine will automatically make it available again in your local VS code or web interface.
• After you authenticate interactively the first time using salloc, you can then submit a batch job with code tunnel to the same machine to open the tunnel in a non-interactive session.
• Remember to kill the job with scancel when you no longer need the tunnel open.
• Use code tunnel --help for additional options such as using a different workspace folder.

Using the Remote - SSH extension¶

To reduce CPU usage and traffic on the log-in node shell-hpc, we have set up a dedicated machine to handle VS Code so remote IDE processes do not consume compute resources on shell nodes.

We support the Remote - SSH extension, but if you need to use R (including installing the R extension on the vscode remote machine), or any other extensions/processes with CPU/Memory reqirements, please use the Remote - Tunnel extension as described above.

Quickstart guide¶

If you're familiar with editing your ssh config file as explained in the connecting guide, then getting your vscode connection will be relatively simple. It should look like this when you're done:

Host shell
    HostName shell.hpc.oregonstate.edu
    User ONIDUSER
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600
    TCPKeepAlive no
    ServerAliveInterval 30

Host vscode
    HostName vs-gateway.hpc.oregonstate.edu
    User ONIDUSER
    ProxyJump shell
    TCPKeepAlive no
    ServerAliveInterval 30

Step-by-step tutorial¶

1. Install the Remote - SSH extension
   • i.e. run ext install ms-vscode-remote.remote-ssh in the quick open panel (ctrl+p)
2. Restart extensions
   • i.e. ctrl+shift+x -> Click restart extensions
   • OR open command pane ctrl+shift+p -> Restart extension host; ctrl+shift+p -> Extensions: Refresh
3. Open the command pane ctrl+shift+p -> Open SSH Configuration File...
   • This usually defaults to: /home/$USERNAME/.ssh/config
   • copy/paste the ~/.ssh/config file contents from above into the file
   • Save the file
4. Test it out by connecting to host i.e.
   • ctrl+shift+p -> Connect to host -> vscode
   • Alternatively, click on the Open a remote window button in the bottom left corner, then Connect to host or Connect Current Window to Host, then vscode

See this graphic for more info:

Additional Config Changes¶

At this point, you likely have a working SSH - Remote session. However, listed below are some additional changes we are requesting everyone make in their vscode settings to keep the remote server performing well for everyone.

With most of the data on the Wildwood infrastructure housed on NFS servers, certain vscode components and extensions are known to produce detrimental I/O loads to NFS-backed filesystems. The setting changes primarily affect how the vscode clients (and installed extensions) search and navigate directories on the remote session.

To limit I/O loads on vs-gateway, please apply the following configurations/settings:

1. Under: User > Features > Remote

   • Default Extensions If Installed Locally: Remove everything in the list except those you legitimately need.
     

2. Under: Remote [SSH: vs-gateway] > Features > Search

   • Follow Symlinks: empty/not checked
   • Max Results: 1000
   • Ripgrep: Max Threads: 4 (a reasonable number we have selected during our tests)
   • Search On Type: empty/not checked (don't continuously search when updating the search term)
     

3. Under: Remote [SSH: vs-gateway] > Features > Terminal

   • Integrated: Enable File Links: notRemote
     

After the edits are complete, close vscode entirely, relaunch, and reconnect to the remote session.

Submitting jobs from vscode machine¶

Slurm is enabled on the vs-gateway machine so that you can submit jobs from the node. The terminal window should work as expected. You can duplicate terminals and use salloc to run interactive jobs as well.

Feedback¶

Please let us know if you run into problems using this method so that we can help you troubleshoot your connection issues.