Watson Studio extension for Visual Studio Code

When you add the Watson Studio extension to Visual Studio Code, you can connect to your Cloud Pak for Data cluster, launch and stop your runtimes, edit files inside your Watson Studio Git-based projects, and run and debug the code within your Cloud Pak for Data runtimes directly from the Visual Studio Code editor.

The connection directs communication through secure web socket tunnels, which are protected by your cluster’s standard authentication setup. The web socket tunnels support the subset of the SSH protocol that is required to remotely edit code or to run and debug code on your remote runtimes.

Service
The Watson Studio service is not available by default. An administrator must install this service on the IBM Cloud Pak for Data platform. To determine whether a service is installed, open the Services catalog and check whether the service is enabled.

Required services
Watson Studio plus appropriate runtime services

Prerequisites

Before downloading and installing the Watson Studio extension, make sure that your administrator has activated Visual Studio Code support. For details, refer to postinstallation tasks for the Watson Studio service.

The Watson Studio extension has been tested with Visual Studio Code 1.72.2 and requires at least Visual Studio Code 1.69.0 or newer to work. While versions older than 1.72.2 should work, try to keep your Visual Studio Code up to date with the latest available version.

Project types

Only Git-based projects can be integrated with the Visual Studio Code extension.

Asset types

All the assets that you can add to a Watson Studio project. For details, refer to Adding data to a project.

Data format

All assets in a Git-based project.

Restrictions

  • Only Git-based projects can be integrated with the Visual Studio Code extension. Configure the Git integration from the CPD UI before you use the project within Visual Studio Code. For more information, refer to Accessing a Git repository.
  • All JupyterLab default environments are supported, except for Spark-based environments and custom environments based on Spark.
  • Visual Studio Code integration does not work if FIPS is enabled on your cluster.
  • When you use the official Python extension from Microsoft, running Jupyter Notebooks is not supported at the moment.
  • x86 is the only supported platform due to restrictions related to remote SSH connection.

Setup steps

To set up the Watson Studio extension for Visual Studio Code:

  1. Download the extension
  2. Install the extension
  3. Configure the extension
  4. Set up SSH on your machine
  5. Optional: Reinstall additional extensions

When the Watson Studio extension is properly set up, you can use it to:

Downloading the Watson Studio extension for Visual Studio Code

To download the Watson Studio extension for Visual Studio Code, use this link: Watson Studio extension.

Installing the Watson Studio extension for Visual Studio Code

To install the Watson Studio extension for Visual Studio Code:

  1. From Visual Studio Code, open the Extensions menu, click More options (...) and then select Install from VSIX.
  2. Select the downloaded watson-studio.vsix file and click Install.
  3. Optional: If you want to be able to access your runtime directly from within Visual Studio Code, install the Remote SSH extension in Visual Studio Code. The extension can be found in Microsoft Marketplace.
    Note: If you don't want to install the Remote SSH extension, you must install a different SSH client on your machine. Connecting to your runtime from within Visual Studio Code without a SSH client is not possible.

Installing the extension from a vsix file

Configuring the Watson Studio extension for Visual Studio Code

To configure the Watson Studio extension for Visual Studio Code:

  1. From Visual Studio Code, open the Settings menu. Alternatively, use the Cmd/Ctrl + Shift + P key combination to open the command palette and then search for Settings UI.
  2. Select Settings UI.
  3. Set the required parameters. Refer to this table:
Parameter Description
watsonstudio.host Hostname of the Cloud Pak for Data Cluster. You can find it in the address bar of your browser when you log in to Cloud Pak for Data. For example, cpd.xxx.xxx.xxx.com.
watsonstudio.userName Username that you use to log in to Cloud Pak for Data
watsonstudio.localPort The port to listen on locally (default: 5681)
watsonstudio.localHost The SSH host to which Remote SSH connects. It can be any host that is specified in the SSH client config file. Refer to Using a separate SSH key for Watson Studio.
The HostName configured in your SSH client config must always point to localhost and the port that is specified in localPort. This allows you to use your own SSH settings, that is a specific private key. Do not change this setting if you're using your default SSH key (id_rsa) Default: 127.0.0.1.
watsonstudio.publicKeyPath Path to the public key file for SSH connection
watsonstudio.verifySSL Optional: whether to verify the certificate of the SSL connection or not. Default: true
watsonstudio.logLevel The log level of the extension
watsonstudio.storeApiKeyInKeychain Whether to store the encrypted Cloud Pak for Data API key in your operating system keychain. Default: true. If you disable this option, the API key is stored in memory only for the duration the current session. When you restart your Visual Studio Code instance, you must re-enter your API key.

Configuring the extension

Setting up SSH on your machine

You can use your existing SSH key pair to work with the Watson Studio Visual Studio Code extension. To check whether you already have an SSH key pair configured:

On Windows-based machines:
Check whether your home directory contains the .ssh directory or run dir "%USERPROFILE%/.ssh".

On MacOS and Linux-based machines:
Check the ~/.ssh directory.

If the only key that you have found is your default key, you can still use it with Watson Studio Visual Studio Code extension. If you do not want to use your default SSH key, you can optionally create a separate SSH key for Watson Studio.

If you do not have any SSH key pairs yet, generate them before you start using the extension.

Note: Currently, only RSA keys are supported and the SSH key must be in the OpenSSH format.

For details on how to generate SSH key pairs, refer to Generating an SSH key pair on MacOS and Linux and Generating an SSH key pair on Windows.

Generating an SSH key pair on MacOS and Linux

To generate an SSH key pair on MacOS and Linux:

  1. Open the Terminal

  2. Type this command:

    ssh-keygen -t rsa -N ""

When you generate a key pair, specify the location of the public key in the watsonstudio.publicKeyPath settings of the extension. Refer to Configuring the extension.

Generating an SSH key pair on Windows

To generate an SSH key pair on Windows:

On Windows 10 or newer with the OpenSSH Client feature enabled:

  1. Open a new cmd command prompt and use the `ssh-keygen utility.
  2. Type this command:
    ssh-keygen -t rsa -N ""

If you are using an older Windows version:

  1. Install a third-party tool, such as PuTTY, to generate an SSH key.
  2. If you are using PuTTY, use the puttygen utility to generate an SSH key pair.

**Note:** PuttyGen does not generate OpenSSH keys by default. To export an OpenSSH key, convert the key: select `Conversions` -> `Export OpenSSH key`.

When you generate a key pair, specify the location of the public key in the watsonstudio.publicKeyPath settings of the extension. Refer to Configuring the extension.

Optional: Using a separate SSH key for Watson Studio

To authenticate, SSH searches for a default key that is named id_rsa in your .ssh directory. If you do not want to use this default key, you can define a separate key for Watson Studio. To use a specific SSH key for Watson Studio:

  1. Add a new entry to your SSH configuration under ~/.ssh/config:

    Host cpdenv
    HostName localhost
    Port 5681 # Same port as watsonstudio.localPort
    IdentityFile ~/.ssh/id_cpd_rsa # Path to your private key

  2. In the Watson Studio extension settings, under watsonstudio.localHost, enter the host. For example, cpdenv.

Optional: reinstalling additional extensions

Your local Visual Studio Code UI is connecting to a Visual Studio Code server that is running in the runtime so most of your extensions must be reinstalled. To do so, open the Extension tab and select Install in SSH for the extensions that you want to be available in your runtime.

Install in SSH option

Connecting to a runtime

Prerequisite:
It is recommended that the environment used by the runtime that you're connecting to has at least 2 CPUs and 4 GB of memory.

The first connection to the runtime takes longer because the Visual Studio Code Server part must be installed. Subsequent connections that are made by the same user are faster.

When you connect to a Cloud Pak for Data cluster that uses a self-signed CA, include your certificate in your operating systems' certificate store (accessed by Visual Studio Code). Otherwise, connection is rejected. Alternatively, you can disable the Use SSL/Verify SSL option to deactivate the verification of SSL certificates. This method is not recommended.

To connect to your runtime:

  1. Use the Cmd/Ctrl + Shift + P key combination to open the command palette and then search for Watson Studio: Connect to Runtime.
  2. Select Watson Studio: Connect to Runtime.
  3. Select the project that you want to use.
  4. Specify the Cloud Pak for Data API Key on your first connection of every session.
  5. Select the environment to be used by the runtime.
  6. When your runtime starts and a secure tunnel is established, you can connect to the runtime by:
    • Using the SSH command shown in the pop-up window.
      Important: You must keep this Visual Studio Code window open, otherwise the connection to the runtime is closed.
    • If you have installed the Remote SSH extension, you can connect by using the Open Runtime button. If you are using the Remote SSH extension, it is recommended that you install the Python extension for Visual Studio Code.

Optional: adding your certificate to your operating system's certificate store on Windows

To add your certificate to your Windows certificate store, follow these steps:

  1. Open the command prompt.
  2. Run certmgr.
  3. Add the certificate in Trusted Root Certification Authorities > Certificates.

Disconnecting from a runtime

To disconnect from a runtime in your Cloud Pak for Data cluster (close the secure tunnel between the runtime and your computer):

  1. Use the Cmd/Ctrl + Shift + P key combination to open the command palette and then search for Watson Studio: Disconnect from Runtime.
  2. Select Watson Studio: Disconnect from Runtime. The Successfully disconnected from runtime message appears.

Stopping a runtime

A runtime continues to run on the cluster unless your stop it by using the Cloud Pak for Data UI or the Visual Studio Code extension. Before you stop a runtime, make sure to disconnect from it first. Refer to Disconnecting from a runtime. Stopping a runtime without disconnecting from it first results in a 502 error.

To stop a running runtime in your Cloud Pak for Data cluster:

  1. Use the Cmd/Ctrl + Shift + P key combination to open the command palette and then search for Watson Studio: Stop Runtime.
  2. Select Watson Studio: Stop Runtime.
  3. Select the runtime that you want to stop.

FAQ and common issues

I lost the connection to the runtime while I was using the Remote SSH extension. How can I reconnect?

If you lose connection to the runtime, connect to the runtime again by using the Watson Studio: Connect to Runtime command. For details, refer to Connecting to a runtime. After you reestablish the connection between the runtime and your local PC, press the Reload button in the Remote SSH window to reconnect through Remote SSH.

Lost connection window

I am unable to connect to Visual Studio Code from my Mac computer. How do I fix this?

Since version 8.8, Open SSH is incompatible with Cloud Pak for Data 4.6.0. This means that you are not able to connect to a 4.6.0 cluster when you use MacOS version 13.0.1 (or later). To solve this issue, upgrade to Cloud Pak for Data version 4.6.1 or later. Possible workaround (not recommended): To connect to a Cloud Pak for Data 4.6.0 cluster on machines with Open SSH version 8.8 or later, type this command:

ssh -o HostKeyAlgorithms=+ssh-rsa 127.0.0.1 -p 5681

Note:
If you are unable to reconnect, try increasing the remote SSH timeout on your machine.

Increasing SSH timeout

When I try to connect to the Cloud Pak for Data cluster, I get an SSL error

Adding your certificate to your operating system's certificate store on Mac

  1. Go to Finder > Applications > Utilities > Keychain Access.
  2. Select System.
  3. Check whether your self-signed CA certificate is on the list. If your certificate is not in the list, to add it:
    1. Import the certificate by using File -> Import items.
    2. When your certificate is imported, double-click the certificate to open it and then select Trust -> When using this certificate -> Always trust.

For other questions on networking and proxy settings, refer to the official Visual Studio Code documentation.

Learn more

Parent topic: Analyzing data and building models