Working on data science projects

Table of Contents

Creating and importing notebooks
Collaborating on notebooks using Git
Working on data science projects
Working with data science pipelines
Working with accelerators
Troubleshooting common problems in Jupyter for administrators
Troubleshooting common problems in Jupyter for users

Creating and importing notebooks

You can create a blank notebook or import a notebook from several different sources.

Creating a new notebook

You can create a new Jupyter notebook from an existing notebook container image to access its resources and properties. The Notebook server control panel contains a list of available container images that you can run as a single-user notebook server.

Prerequisites

Ensure that you have logged in to Open Data Hub.
Ensure that you have launched your notebook server and logged in to Jupyter.
The notebook image exists in a registry, image stream, and is accessible.

Procedure

Click File → New → Notebook.
If prompted, select a kernel for your notebook from the list.

If you want to use a kernel, click Select. If you do not want to use a kernel, click No Kernel.

Verification

Check that the notebook file is visible in the JupyterLab interface.

Notebook images for data scientists

Open Data Hub contains Jupyter notebook images optimized with industry-leading tools and libraries required for your data science work. To provide a consistent, stable platform for your model development, all notebook images contain the same version of Python. Notebook images available on Open Data Hub are pre-built and ready for you to use immediately after Open Data Hub is installed or upgraded.

When a new version of a notebook image is released, the previous version remains available on the cluster. This gives you time to migrate your work to the latest version of the notebook image. Legacy notebook image versions, that is, not the two most recent versions, might still be available for selection. Legacy image versions include a label that indicates that the image is out-of-date. To use the latest package versions, use the most recently added notebook image.

Open Data Hub contains the following notebook images that are available by default.

Table 1. Default notebook images

Image name

Description

CUDA

If you are working with compute-intensive data science models that require GPU support, use the Compute Unified Device Architecture (CUDA) notebook image to gain access to the NVIDIA CUDA Toolkit. Using this toolkit, you can optimize your work using GPU-accelerated libraries and optimization tools.

Standard Data Science

Use the Standard Data Science notebook image for models that do not require TensorFlow or PyTorch. This image contains commonly used libraries to assist you in developing your machine learning models.

TensorFlow

TensorFlow is an open source platform for machine learning. With TensorFlow, you can build, train and deploy your machine learning models. TensorFlow contains advanced data visualization features, such as computational graph visualizations. It also allows you to easily monitor and track the progress of your models.

PyTorch

PyTorch is an open source machine learning library optimized for deep learning. If you are working with computer vision or natural language processing models, use the Pytorch notebook image.

Minimal Python

If you do not require advanced machine learning features, or additional resources for compute-intensive data science work, you can use the Minimal Python image to develop your models.

TrustyAI

Use the TrustyAI notebook image to leverage your data science work with model explainability, tracing, and accountability, and runtime monitoring.

HabanaAI

The HabanaAI notebook image optimizes high-performance deep learning (DL) with Habana Gaudi devices. Habana Gaudi devices accelerate DL training workloads and maximize training throughput and efficiency.

code-server

With the code-server notebook image, you can customize your notebook environment to meet your needs using a variety of extensions to add new languages, themes, debuggers, and connect to additional services. Enhance the efficiency of your data science work with syntax highlighting, auto-indentation, and bracket matching, as well as an automatic task runner for seamless automation. See code-server in GitHub for more information.

Note	Elyra-based pipelines are not available with the code-server notebook image.

RStudio Server

Use the RStudio Server notebook image to access the RStudio IDE, an integrated development environment for R, a programming language for statistical computing and graphics. See the RStudio Server site for more information.

CUDA - RStudio Server

Use the CUDA - RStudio Server notebook image to access the RStudio IDE and NVIDIA CUDA Toolkit. RStudio is an integrated development environment for R, a programming language for statistical computing and graphics. With the NVIDIA CUDA toolkit, you can optimize your work using GPU-accelerated libraries and optimization tools. See the RStudio Server site for more information.

Uploading an existing notebook file from local storage

You can load an existing notebook from local storage into JupyterLab to continue work, or adapt a project for a new use case.

Prerequisites

Credentials for logging in to Jupyter.
A launched and running notebook server.
A notebook file exists in your local storage.

Procedure

In the File Browser in the left sidebar of the JupyterLab interface, click Upload Files ().
Locate and select the notebook file and click Open.

The file is displayed in the File Browser.

Verification

The notebook file displays in the File Browser in the left sidebar of the JupyterLab interface.
You can open the notebook file in JupyterLab.

Uploading an existing notebook file from a Git repository using JupyterLab

You can use the JupyterLab user interface to clone a Git repository into your workspace to continue your work or integrate files from an external project.

Prerequisites

A launched and running Jupyter server.
Read access for the Git repository you want to clone.

Procedure

Copy the HTTPS URL for the Git repository.
- On GitHub, click ⤓ Code → HTTPS and click the Clipboard button.
- On GitLab, click Clone and click the Clipboard button under Clone with HTTPS.
In the JupyterLab interface, click the Git Clone button ().

You can also click Git → Clone a repository in the menu, or click the Git icon () and click the Clone a repository button.

The Clone a repo dialog appears.
Enter the HTTPS URL of the repository that contains your notebook.
Click CLONE.
If prompted, enter your username and password for the Git repository.

Verification

Check that the contents of the repository are visible in the file browser in JupyterLab, or run the ls command in the terminal to verify that the repository is shown as a directory.

Uploading an existing notebook file from a Git repository using the command line interface

You can use the command line interface to clone a Git repository into your workspace to continue your work or integrate files from an external project.

Prerequisites

A launched and running Jupyter server.

Procedure

Copy the HTTPS URL for the Git repository.
- On GitHub, click ⤓ Code → HTTPS and click the Clipboard button.
- On GitLab, click Clone and click the Clipboard button under Clone with HTTPS.
In JupyterLab, click File → New → Terminal to open a terminal window.

Enter the git clone command.

git clone <git-clone-URL>

Replace `<git-clone-URL>` with the HTTPS URL, for example:

[1234567890@jupyter-nb-jdoe ~]$ git clone https://github.com/example/myrepo.git
Cloning into myrepo...
remote: Enumerating objects: 11, done.
remote: Counting objects: 100% (11/11), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 2821 (delta 1), reused 5 (delta 1), pack-reused 2810
Receiving objects: 100% (2821/2821), 39.17 MiB | 23.89 MiB/s, done.
Resolving deltas: 100% (1416/1416), done.

Verification

Check that the contents of the repository are visible in the file browser in JupyterLab, or run the ls command in the terminal to verify that the repository is shown as a directory.

Collaborating on notebooks using Git

If your notebooks or other files are stored in Git version control, you can import them from a Git repository onto your notebook server to work with them in JupyterLab. When you are ready, you can push your changes back to the Git repository so that others can review or use your models.

Uploading an existing notebook file from a Git repository using JupyterLab

You can use the JupyterLab user interface to clone a Git repository into your workspace to continue your work or integrate files from an external project.

Prerequisites

A launched and running Jupyter server.
Read access for the Git repository you want to clone.

Procedure

Copy the HTTPS URL for the Git repository.
- On GitHub, click ⤓ Code → HTTPS and click the Clipboard button.
- On GitLab, click Clone and click the Clipboard button under Clone with HTTPS.
In the JupyterLab interface, click the Git Clone button ().

You can also click Git → Clone a repository in the menu, or click the Git icon () and click the Clone a repository button.

The Clone a repo dialog appears.
Enter the HTTPS URL of the repository that contains your notebook.
Click CLONE.
If prompted, enter your username and password for the Git repository.

Verification

Check that the contents of the repository are visible in the file browser in JupyterLab, or run the ls command in the terminal to verify that the repository is shown as a directory.

Uploading an existing notebook file from a Git repository using the command line interface

You can use the command line interface to clone a Git repository into your workspace to continue your work or integrate files from an external project.

Prerequisites

A launched and running Jupyter server.

Procedure

Copy the HTTPS URL for the Git repository.
- On GitHub, click ⤓ Code → HTTPS and click the Clipboard button.
- On GitLab, click Clone and click the Clipboard button under Clone with HTTPS.
In JupyterLab, click File → New → Terminal to open a terminal window.

Enter the git clone command.

git clone <git-clone-URL>

Replace `<git-clone-URL>` with the HTTPS URL, for example:

[1234567890@jupyter-nb-jdoe ~]$ git clone https://github.com/example/myrepo.git
Cloning into myrepo...
remote: Enumerating objects: 11, done.
remote: Counting objects: 100% (11/11), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 2821 (delta 1), reused 5 (delta 1), pack-reused 2810
Receiving objects: 100% (2821/2821), 39.17 MiB | 23.89 MiB/s, done.
Resolving deltas: 100% (1416/1416), done.

Verification

Check that the contents of the repository are visible in the file browser in JupyterLab, or run the ls command in the terminal to verify that the repository is shown as a directory.

Updating your project with changes from a remote Git repository

You can pull changes made by other users into your data science project from a remote Git repository.

Prerequisites

You have configured the remote Git repository.
You have already imported the Git repository into JupyterLab, and the contents of the repository are visible in the file browser in JupyterLab.
You have permissions to pull files from the remote Git repository to your local repository.
You have credentials for logging in to Jupyter.
You have a launched and running Jupyter server.

Procedure

In the JupyterLab interface, click the Git button ().
Click the Pull latest changes button ().

Verification

You can view the changes pulled from the remote repository in the History tab of the Git pane.

Pushing project changes to a Git repository

To build and deploy your application in a production environment, upload your work to a remote Git repository.

Prerequisites

You have opened a notebook in the JupyterLab interface.
You have already added the relevant Git repository to your notebook server.
You have permission to push changes to the relevant Git repository.
You have installed the Git version control extension.

Procedure

Click File → Save All to save any unsaved changes.
Click the Git icon () to open the Git pane in the JupyterLab interface.
Confirm that your changed files appear under Changed.

If your changed files appear under Untracked, click Git → Simple Staging to enable a simplified Git process.
Commit your changes.
1. Ensure that all files under Changed have a blue checkmark beside them.
2. In the Summary field, enter a brief description of the changes you made.
3. Click Commit.
Click Git → Push to Remote to push your changes to the remote repository.
When prompted, enter your Git credentials and click OK.

Verification

Your most recently pushed changes are visible in the remote Git repository.

Working on data science projects

As a data scientist, you can organize your data science work into a single project. A data science project in Open Data Hub can consist of the following components:

Workbenches: Creating a workbench allows you to add a Jupyter notebook to your project.
Cluster storage: For data science projects that require data retention, you can add cluster storage to the project.
Data connections: Adding a data connection to your project allows you to connect data inputs to your workbenches.
Pipelines: Standardize and automate machine learning workflows to enable you to further enhance and deploy your data science models.
Models and model servers: Deploy a trained data science model to serve intelligent applications. Your model is deployed with an endpoint that allows applications to send requests to the model.
Bias metrics for models: Creating bias metrics allows you to monitor your machine learning models for bias.

Important

If you create an OpenShift project outside of the Open Data Hub user interface, the project is not shown on the Data Science Projects page. In addition, you cannot use features exclusive to Open Data Hub, such as workbenches and model serving, with a standard OpenShift project.

To classify your OpenShift project as a data science project, and to make available features exclusive to Open Data Hub, you must add the label opendatahub.io/dashboard: 'true' to the project namespace. After you add this label, your project is subsequently shown on the Data Science Projects page.

Using data science projects

Creating a data science project

To start your data science work, create a data science project. Creating a project helps you organize your work in one place. You can also enhance your data science project by adding the following functionality:

Workbenches
Storage for your project’s cluster
Data connections
Data science pipelines
Model servers
Bias monitoring for your models

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click Create data science project.

The Create a data science project dialog opens.
Enter a name for your data science project.
Optional: Edit the resource name for your data science project. The resource name must consist of lowercase alphanumeric characters, -, and must start and end with an alphanumeric character.
Enter a description for your data science project.
Click Create.

A project details page opens. From this page, you can create workbenches, add cluster storage and data connections, import pipelines, and deploy models.

Verification

The project that you created is displayed on the Data Science Projects page.

Updating a data science project

You can update your data science project’s details by changing your project’s name and description text.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the action menu (⋮) beside the project whose details you want to update and click Edit project.

The Edit data science project dialog opens.
Optional: Update the name for your data science project.
Optional: Update the description for your data science project.
Click Update.

Verification

The data science project that you updated is displayed on the Data Science Projects page.

Deleting a data science project

You can delete data science projects so that they do not appear on the Open Data Hub Data Science Projects page when you no longer want to use them.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users) in OpenShift.
You have created a data science project.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the action menu (⋮) beside the project that you want to delete and then click Delete project.

The Delete project dialog opens.
Enter the project name in the text field to confirm that you intend to delete it.
Click Delete project.

Verification

The data science project that you deleted is no longer displayed on the Data Science Projects page.
Deleting a data science project deletes any associated workbenches, data science pipelines, cluster storage, and data connections. This data is permanently deleted and is not recoverable.

Using project workbenches

Creating a project workbench

To examine and work with models in an isolated area, you can create a workbench. You can use this workbench to create a Jupyter notebook from an existing notebook container image to access its resources and properties. For data science projects that require data retention, you can add container storage to the workbench you are creating. If you require extra power for use with large datasets, you can assign accelerators to your workbench to optimize performance.

Prerequisites

You have logged in to Open Data Hub.
If you use specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that you can add a workbench to.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to add the workbench to.

A project details page opens.
Click the Workbenches tab.
Click Create workbench.

The Create workbench page opens.
Configure the properties of the workbench you are creating.
1. In the Name field, enter a name for your workbench.
2. Optional: In the Description field, enter a description to define your workbench.
3. In the Notebook image section, complete the fields to specify the notebook image to use with your workbench.
  1. From the Image selection list, select a notebook image.
4. In the Deployment size section, specify the size of your deployment instance.
  1. From the Container size list, select a container size for your server.
  2. Optional: From the Accelerator list, select an accelerator.
  3. If you selected an accelerator in the preceding step, specify the number of accelerators to use.
5. Optional: Select and specify values for any new environment variables.

Configure the storage for your Open Data Hub cluster.
1. Select Create new persistent storage to create storage that is retained after you log out of Open Data Hub. Complete the relevant fields to define the storage.
2. Select Use existing persistent storage to reuse existing storage and select the storage from the Persistent storage list.
To use a data connection, in the Data connections section, select the Use a data connection checkbox.
- Create a new data connection as follows:
  
  Select Create new data connection.
  
  In the Name field, enter a unique name for the data connection.
  
  In the Access key field, enter the access key ID for the S3-compatible object storage provider.
  
  In the Secret key field, enter the secret access key for the S3-compatible object storage account that you specified.
  
  In the Endpoint field, enter the endpoint of your S3-compatible object storage bucket.
  
  In the Region field, enter the default region of your S3-compatible object storage account.
  
  In the Bucket field, enter the name of your S3-compatible object storage bucket.
- Use an existing data connection as follows:
  
  Select Use existing data connection.
  
  From the Data connection list, select a data connection that you previously defined.
1. Click Create workbench.

Verification

The workbench that you created appears on the Workbenches tab for the project.
Any cluster storage that you associated with the workbench during the creation process appears on the Cluster storage tab for the project.
The Status column on the Workbenches tab displays a status of Starting when the workbench server is starting, and Running when the workbench has successfully started.

Starting a workbench

You can manually start a data science project’s workbench from the Workbenches tab on the project details page. By default, workbenches start immediately after you create them.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that contains a workbench.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project whose workbench you want to start.

A project details page opens.
Click the Workbenches tab.
Click the toggle in the Status column for the relevant workbench to start a workbench that is not running.

The status of the workbench that you started changes from Stopped to Running. After the workbench has started, click Open to open the workbench’s notebook.

Verification

The workbench that you started appears on the Workbenches tab for the project, with the status of Running.

Updating a project workbench

If your data science work requires you to change your workbench’s notebook image, container size, or identifying information, you can update the properties of your project’s workbench. If you require extra power for use with large datasets, you can assign accelerators to your workbench to optimize performance.

Prerequisites

You have logged in to Open Data Hub.
If you use specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that has a workbench.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project whose workbench you want to update.

A project details page opens.
Click the Workbenches tab.
Click the action menu (⋮) beside the workbench that you want to update and then click Edit workbench.

The Edit workbench page opens.
Update any of the workbench properties and then click Update workbench.

Verification

The workbench that you updated appears on the Workbenches tab for the project.

Deleting a workbench from a data science project

You can delete workbenches from your data science projects to help you remove Jupyter notebooks that are no longer relevant to your work.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project with a workbench.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to delete the workbench from.

A project details page opens.
Click the Workbenches tab.
Click the action menu (⋮) beside the workbench that you want to delete and then click Delete workbench.

The Delete workbench dialog opens.
Enter the name of the workbench in the text field to confirm that you intend to delete it.
Click Delete workbench.

Verification

The workbench that you deleted is no longer displayed in the Workbenches tab for the project.
The custom resource (CR) associated with the workbench’s Jupyter notebook is deleted.

Using data connections

Adding a data connection to your data science project

You can enhance your data science project by adding a connection to a data source. When you want to work with a very large data sets, you can store your data in an S3-compatible object storage bucket, so that you do not fill up your local storage. You also have the option of associating the data connection with an existing workbench that does not already have a connection.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that you can add a data connection to.
You have access to S3-compatible object storage.
If you intend to add the data connection to an existing workbench, you have saved any data in the workbench to avoid losing work.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to add a data connection to.

A project details page opens.
Click the Data connections tab.
Click Add data connection.

The Add data connection dialog opens.
Enter a name for the data connection.
In the Access key field, enter the access key ID for your S3-compatible object storage provider.
In the Secret key field, enter the secret access key for the S3-compatible object storage account you specified.
In the Endpoint field, enter the endpoint of your S3-compatible object storage bucket.
In the Region field, enter the default region of your S3-compatible object storage account.
In the Bucket field, enter the name of your S3-compatible object storage bucket.
Optional: From the Connected workbench list, select a workbench to connect.
Click Add data connection.

Verification

The data connection that you added appears in the Data connections tab for the project.
If you selected a workbench, the workbench is visible in the Connected workbenches column in the Data connections tab for the project.

Deleting a data connection

You can delete data connections from your data science projects to help you remove connections that are no longer relevant to your work.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project with a data connection.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to delete the data connection from.

A project details page opens.
Click the Data connections tab.
Click the action menu (⋮) beside the data connection that you want to delete and then click Delete data connection.

The Delete data connection dialog opens.
Enter the name of the data connection in the text field to confirm that you intend to delete it.
Click Delete data connection.

Verification

The data connection that you deleted is no longer displayed in the Data connections tab for the project.

Updating a connected data source

To use an existing data source with a different workbench, you can change the data source that is connected to your project’s workbench.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project, created a workbench, and you have defined a data connection.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project whose data source you want to change.

A project details page opens.
Click the Data connections tab.
Click the action menu (⋮) beside the data source that you want to change and then click Edit data connection.

The Edit data connection dialog opens.
In the Connected workbench section, select an existing workbench from the list.
Click Update data connection.

Verification

The updated data connection is displayed in the Data connections tab for the project.
You can access your S3 data source using environment variables in the connected workbench.

Configuring cluster storage

Adding cluster storage to your data science project

For data science projects that require data to be retained, you can add cluster storage to the project. Additionally, you can also connect cluster storage to a specific project’s workbench.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that you can add cluster storage to.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to add the cluster storage to.

A project details page opens.
Click the Cluster storage tab.
Click Add cluster storage.

The Add storage dialog opens.
Enter a name for the cluster storage.
Enter a description for the cluster storage.
Under Persistent storage size, enter a new size in gibibytes. The minimum size is 1 GiB, and the maximum size is 16384 GiB.
Optional: Select a workbench from the list to connect the cluster storage to an existing workbench.
If you selected a workbench to connect the storage to, enter the storage directory in the Mount folder field.
Click Add storage.

Verification

The cluster storage that you added appears in the Cluster storage tab for the project.
A new persistent volume claim (PVC) is created with the storage size that you defined.
The persistent volume claim (PVC) is visible as an attached storage in the Workbenches tab for the project.

Updating cluster storage

If your data science work requires you to change the identifying information of a project’s cluster storage or the workbench that the storage is connected to, you can update your project’s cluster storage to change these properties.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that contains cluster storage.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project whose storage you want to update.

A project details page opens.
Click the Cluster storage tab.
Click the action menu (⋮) beside the storage that you want to update and then click Edit storage.

The Edit storage page opens.
Update the storage’s properties.
1. Update the name for the storage, if applicable.
2. Update the description for the storage, if applicable.
3. Increase the Persistent storage size for the storage, if applicable.
  
  Note that you can only increase the storage size. Updating the storage size restarts the workbench and makes it unavailable for a period of time that is usually proportional to the size change.
4. Update the workbench that the storage is connected to, if applicable.
5. If you selected a new workbench to connect the storage to, enter the storage directory in the Mount folder field.
Click Update storage.

If you increased the storage size, the workbench restarts and is unavailable for a period of time that is usually proportional to the size change.

Verification

The storage that you updated appears in the Cluster storage tab for the project.

Deleting cluster storage from a data science project

You can delete cluster storage from your data science projects to help you free up resources and delete unwanted storage space.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project with cluster storage.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to delete the storage from.

A project details page opens.
Click the Cluster storage tab.
Click the action menu (⋮) beside the storage that you want to delete and then click Delete storage.

The Delete storage dialog opens.
Enter the name of the storage in the text field to confirm that you intend to delete it.
Click Delete storage.

Verification

The storage that you deleted is no longer displayed in the Cluster storage tab for the project.
The persistent volume (PV) and persistent volume claim (PVC) associated with the cluster storage are both permanently deleted. This data is not recoverable.

Configuring data science pipelines

Configuring a pipeline server

Before you can successfully create a pipeline in Open Data Hub, you must configure a pipeline server. This task includes configuring where your pipeline artifacts and data are stored.

Note

You are not required to specify any storage directories when configuring a data connection for your pipeline server. When you import a pipeline, the /pipelines folder is created in the root folder of the bucket, containing a YAML file for the pipeline. If you upload a new version of the same pipeline, a new YAML file with a different ID is added to the /pipelines folder.

When you run a pipeline, the artifacts are stored in the /pipeline-name folder in the root folder of the bucket.

Important

If you use an external MySQL database and upgrade to Open Data Hub 2.10.0, the database is migrated to DSP 2.0 format, making it incompatible with earlier versions of Open Data Hub.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that you can add a pipeline server to.
You have an existing S3-compatible object storage bucket and you have configured write access to your S3 bucket on your storage account.
If you are configuring a pipeline server with an external MySQL database, your database must use MySQL version 5.x.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to configure a pipeline server for.

A project details page opens.
Click the Pipelines tab.
Click Configure pipeline server.

The Configure pipeline server dialog appears.

In the Object storage connection section, provide values for the mandatory fields:

In the Access key field, enter the access key ID for the S3-compatible object storage provider.
In the Secret key field, enter the secret access key for the S3-compatible object storage account that you specified.
In the Endpoint field, enter the endpoint of your S3-compatible object storage bucket.
In the Region field, enter the default region of your S3-compatible object storage account.

In the Bucket field, enter the name of your S3-compatible object storage bucket.

Important

If you specify incorrect data connection settings, you cannot update these settings on the same pipeline server. Therefore, you must delete the pipeline server and configure another one.

In the Database section, click Show advanced database options to specify the database to store your pipeline data and select one of the following sets of actions:
- Select Use default database stored on your cluster to deploy a MariaDB database in your project.
- Select Connect to external MySQL database to add a new connection to an external database that your pipeline server can access.
  1. In the Host field, enter the database’s host name.
  2. In the Port field, enter the database’s port.
  3. In the Username field, enter the default user name that is connected to the database.
  4. In the Password field, enter the password for the default user account.
  5. In the Database field, enter the database name.
Click Configure pipeline server.

Verification

In the Pipelines tab for the project:

The Import pipeline button is available.
When you click the action menu (⋮) and then click View pipeline server configuration, the pipeline server details are displayed.

Defining a pipeline

The Kubeflow Pipelines SDK enables you to define end-to-end machine learning and data pipelines. Use the latest Kubeflow Pipelines 2.0 SDK to build your data science pipeline in Python code. After you have built your pipeline, use the SDK to compile it into an Intermediate Representation (IR) YAML file. After defining the pipeline, you can import the YAML file to the Open Data Hub dashboard to enable you to configure its execution settings.

You can also use the Elyra JupyterLab extension to create and run data science pipelines within JupyterLab. For more information about the Elyra JupyterLab extension, see Elyra Documentation.

Additional resources

Importing a data science pipeline

To help you begin working with data science pipelines in Open Data Hub, you can import a YAML file containing your pipeline’s code to an active pipeline server, or you can import the YAML file from a URL. This file contains a Kubeflow pipeline compiled by using the Kubeflow compiler. After you have imported the pipeline to a pipeline server, you can execute the pipeline by creating a pipeline run.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have compiled your pipeline with the Kubeflow compiler and you have access to the resulting YAML file.
If you are uploading your pipeline from a URL, the URL is publicly accessible.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that you want to import a pipeline to.
Click Import pipeline.
In the Import pipeline dialog, enter the details for the pipeline that you are importing.
1. In the Pipeline name field, enter a name for the pipeline that you are importing.
2. In the Pipeline description field, enter a description for the pipeline that you are importing.
3. Select where you want to import your pipeline from by performing one of the following actions:
  - Select Upload a file to upload your pipeline from your local machine’s file system. Import your pipeline by clicking upload or by dragging and dropping a file.
  - Select Import by url to upload your pipeline from a URL and then enter the URL into the text box.
4. Click Import pipeline.

Verification

The pipeline that you imported appears on the Pipelines page and on the Pipelines tab on the project details page.

Configuring access to data science projects

To enable you to work collaboratively on your data science projects with other users, you can share access to your project. After creating your project, you can then set the appropriate access permissions from the Open Data Hub user interface.

You can assign the following access permission levels to your data science projects:

Admin - Users can modify all areas of a project, including its details (project name and description), components, and access permissions.
Edit - Users can modify a project’s components, such as its workbench, but they cannot edit a project’s access permissions or its details (project name and description).

To enable your organization to work collaboratively, you can share access to your data science project with other users and groups.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
From the list of data science projects, click the name of the data science project that you want to share access to.

A project details page opens.
Click the Permissions tab.

The Permissions page for the project opens.
Provide one or more users with access to the project.
1. In the Users section, click Add user.
2. In the Name field, enter the user name of the user whom you want to provide access to the project.
3. From the Permissions list, select one of the following access permission levels:
  - Admin: Users with this access level can edit project details and manage access to the project.
  - Edit: Users with this access level can view and edit project components, such as its workbenches, data connections, and storage.
4. To confirm your entry, click Confirm ().
5. Optional: To add an additional user, click Add user and repeat the process.
Provide one or more OpenShift groups with access to the project.
1. In the Groups section, click Add group.
2. From the Name list, select a group to provide access to the project.
  
  Note
  
  If you do not have cluster-admin permissions, the Name list is not visible. Instead, an input field is displayed enabling you to configure group permissions.
3. From the Permissions list, select one of the following access permission levels:
  - Admin: Groups with this access permission level can edit project details and manage access to the project.
  - Edit: Groups with this access permission level can view and edit project components, such as its workbenches, data connections, and storage.
4. To confirm your entry, click Confirm ().
5. Optional: To add an additional group, click Add group and repeat the process.

Verification

Users to whom you provided access to the project can perform only the actions permitted by their access permission level.
The Users and Groups sections on the Permissions tab show the respective users and groups that you provided with access to the project.

Updating access to a data science project

To change the level of collaboration on your data science project, you can update the access permissions of users and groups who have access to your project.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project.
You have previously shared access to your project with other users or groups.
You have administrator permissions or you are the project owner.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to change the access permissions of.

A project details page opens.
Click the Permissions tab.

The Permissions page for the project opens.
Update the user access permissions to the project.
1. In the Name field, update the user name of the user whom you want to provide access to the project.
2. From the Permissions list, update the user access permissions by selecting one of the following:
  - Admin: Users with this access level can edit project details and manage access to the project.
  - Edit: Users with this access level can view and edit project components, such as its workbenches, data connections, and storage.
3. To confirm the update to the entry, click Confirm ().
Update the OpenShift groups access permissions to the project.
1. From the Name list, update the group that has access to the project by selecting another group from the list.
  
  Note
  
  If you do not have cluster-admin permissions, the Name list is not visible. Instead, you can configure group permissions in the input field that appears.
2. From the Permissions list, update the group access permissions by selecting one of the following:
  - Admin: Groups with this access permission level can edit project details and manage access to the project.
  - Edit: Groups with this access permission level can view and edit project components, such as its workbenches, data connections, and storage.
3. To confirm the update to the entry, click Confirm ().

Verification

The Users and Groups sections on the Permissions tab show the respective users and groups whose project access permissions you changed.

Removing access to a data science project

If you no longer want to work collaboratively on your data science project, you can restrict access to your project by removing users and groups that you previously provided access to your project.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project.
You have previously shared access to your project with other users or groups.
You have administrator permissions or you are the project owner.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to change the access permissions of.

A project details page opens.
Click the Permissions tab.

The Permissions page for the project opens.
Click the action menu (⋮) beside the user or group whose access permissions you want to revoke and click Delete.

Verification

Users whose access you have revoked can no longer perform the actions that were permitted by their access permission level.

Viewing Python packages installed on your notebook server

You can check which Python packages are installed on your notebook server and which version of the package you have by running the pip tool in a notebook cell.

Prerequisites

Procedure

Enter the following in a new cell in your notebook:
```
!pip list
```
Run the cell.

Verification

The output shows an alphabetical list of all installed Python packages and their versions. For example, if you use this command immediately after creating a notebook server that uses the Minimal image, the first packages shown are similar to the following:

Package                           Version
--------------------------------- ----------
aiohttp                           3.7.3
alembic                           1.5.2
appdirs                           1.4.4
argo-workflows                    3.6.1
argon2-cffi                       20.1.0
async-generator                   1.10
async-timeout                     3.0.1
attrdict                          2.0.1
attrs                             20.3.0
backcall                          0.2.0

Installing Python packages on your notebook server

You can install Python packages that are not part of the default notebook server image by adding the package and the version to a requirements.txt file and then running the pip install command in a notebook cell.

Note	You can also install packages directly, but using a `requirements.txt` file so that the packages stated in the file can be easily re-used across different notebooks is recommended. In addition, using a `requirements.txt` file is also useful when using a S2I build to deploy a model.

Prerequisites

Procedure

Create a new text file using one of the following methods:
- Click + to open a new launcher and click Text file.
- Click File → New → Text File.
Rename the text file to requirements.txt.
1. Right-click on the name of the file and click Rename Text. The Rename File dialog opens.
2. Enter requirements.txt in the New Name field and click Rename.
Add the packages to install to the requirements.txt file.
```
altair
```
You can specify the exact version to install by using the == (equal to) operator, for example:
```
altair==4.1.0
```
Specifying exact package versions to enhance the stability of your notebook server over time is recommended. New package versions can introduce undesirable or unexpected changes in your environment’s behavior. To install multiple packages at the same time, place each package on a separate line.
Install the packages in requirements.txt to your server using a notebook cell.
1. Create a new cell in your notebook and enter the following command:
  !pip install -r requirements.txt
2. Run the cell by pressing Shift and Enter.
Important

This command installs the package on your notebook server, but you must still run the import directive in a code cell to use the package in your code.

import altair

Verification

Confirm that the packages in requirements.txt appear in the list of packages installed on the notebook server. See Viewing Python packages installed on your notebook server for details.

Updating notebook server settings by restarting your server

You can update the settings on your notebook server by stopping and relaunching the notebook server. For example, if your server runs out of memory, you can restart the server to make the container size larger.

Prerequisites

A running notebook server.
Log in to Jupyter.

Procedure

Click File → Hub Control Panel.

The Notebook server control panel opens.
Click the Stop notebook server button.

The Stop server dialog opens.
Click Stop server to confirm your decision.

The Start a notebook server page opens.
Update the relevant notebook server settings and click Start server.

Verification

The notebook server starts and contains your updated settings.

Additional resources

Launching Jupyter and starting a notebook server

Working with data science pipelines

As a data scientist, you can enhance your data science projects on Open Data Hub by building portable machine learning (ML) workflows with data science pipelines, using Docker containers. This enables you to standardize and automate machine learning workflows to enable you to develop and deploy your data science models.

For example, the steps in a machine learning workflow might include items such as data extraction, data processing, feature extraction, model training, model validation, and model serving. Automating these activities enables your organization to develop a continuous process of retraining and updating a model based on newly received data. This can help resolve challenges related to building an integrated machine learning deployment and continuously operating it in production.

You can also use the Elyra JupyterLab extension to create and run data science pipelines within JupyterLab. For more information, see Working with pipelines in JupyterLab.

From Open Data Hub version 2.10.0, data science pipelines are based on KubeFlow Pipelines (KFP) version 2.0. For more information, see Enabling Data Science Pipelines 2.0.

A data science pipeline in Open Data Hub consists of the following components:

Pipeline server: A server that is attached to your data science project and hosts your data science pipeline.
Pipeline: A pipeline defines the configuration of your machine learning workflow and the relationship between each component in the workflow.
- Pipeline code: A definition of your pipeline in a YAML file.
- Pipeline graph: A graphical illustration of the steps executed in a pipeline run and the relationship between them.
Pipeline run: An execution of your pipeline.
- Active run: A pipeline run that is in its execution phase, or is stopped.
- Scheduled run: A pipeline run scheduled to execute at least once.
- Archived run: A pipeline run that resides in the run archive and is no longer required.

This feature is based on Kubeflow Pipelines 2.0. Use the latest Kubeflow Pipelines 2.0 SDK to build your data science pipeline in Python code. After you have built your pipeline, use the SDK to compile it into an Intermediate Representation (IR) YAML file. The Open Data Hub user interface enables you to track and manage pipelines and pipeline runs.

You can store your pipeline artifacts in an S3-compatible object storage bucket so that you do not consume local storage. To do this, you must first configure write access to your S3 bucket on your storage account.

Enabling Data Science Pipelines 2.0

From Open Data Hub version 2.10.0, data science pipelines are based on KubeFlow Pipelines (KFP) version 2.0. DSP 2.0 is enabled and deployed by default in Open Data Hub.

Note	The `PipelineConf` class is deprecated, and there is no KFP 2.0 equivalent.

Important

Data Science Pipelines (DSP) 2.0 contains an installation of Argo Workflows. Open Data Hub does not support direct customer usage of this installation of Argo Workflows.

To install or upgrade to Open Data Hub 2.10.0 with DSP, ensure that your cluster does not have an existing installation of Argo Workflows that is not installed by Open Data Hub.

Argo Workflows resources that are created by Open Data Hub have the following labels in the OpenShift Console under Administration > CustomResourceDefinitions, in the argoproj.io group:

 labels:
    app.kubernetes.io/part-of: data-science-pipelines-operator
    app.opendatahub.io/data-science-pipelines-operator: 'true'

Installing Open Data Hub with DSP 2.0

To install Open Data Hub 2.10.0, ensure that there is no installation of Argo Workflows that is not installed by DSP on your cluster, and follow the installation steps described in Installing Open Data Hub.

If there is an existing installation of Argo Workflows that is not installed by DSP on your cluster, DSP will be disabled after you install Open Data Hub 2.10.0 with DSP.

To enable data science pipelines, remove the separate installation of Argo Workflows from your cluster. Data Science Pipelines will be enabled automatically.

Upgrading to DSP 2.0

Important

After you upgrade to Open Data Hub 2.10.0, pipelines created with DSP 1.0 will continue to run, but will be inaccessible from the Open Data Hub dashboard. We recommend that current DSP users do not upgrade to Open Data Hub 2.10.0 until you are ready to migrate to the new pipelines solution.

To upgrade to Open Data Hub 2.10.0 with DSP 2.0, ensure that there is no installation of Argo Workflows that is not installed by DSP on your cluster, and follow the upgrade steps described in Upgrading Open Data Hub.

If you upgrade to Open Data Hub 2.10.0 with DSP enabled and an Argo Workflows installation that is not installed by DSP exists on your cluster, Open Data Hub components will not be upgraded. To complete the component upgrade, disable DSP or remove the separate installation of Argo Workflows. The component upgrade will complete automatically.

Managing data science pipelines

Configuring a pipeline server

Before you can successfully create a pipeline in Open Data Hub, you must configure a pipeline server. This task includes configuring where your pipeline artifacts and data are stored.

Note

When you run a pipeline, the artifacts are stored in the /pipeline-name folder in the root folder of the bucket.

Important

If you use an external MySQL database and upgrade to Open Data Hub 2.10.0, the database is migrated to DSP 2.0 format, making it incompatible with earlier versions of Open Data Hub.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that you can add a pipeline server to.
You have an existing S3-compatible object storage bucket and you have configured write access to your S3 bucket on your storage account.
If you are configuring a pipeline server with an external MySQL database, your database must use MySQL version 5.x.

Procedure

From the Open Data Hub dashboard, click Data Science Projects.

The Data Science Projects page opens.
Click the name of the project that you want to configure a pipeline server for.

A project details page opens.
Click the Pipelines tab.
Click Configure pipeline server.

The Configure pipeline server dialog appears.

In the Object storage connection section, provide values for the mandatory fields:

In the Access key field, enter the access key ID for the S3-compatible object storage provider.
In the Secret key field, enter the secret access key for the S3-compatible object storage account that you specified.
In the Endpoint field, enter the endpoint of your S3-compatible object storage bucket.
In the Region field, enter the default region of your S3-compatible object storage account.

In the Bucket field, enter the name of your S3-compatible object storage bucket.

Important

If you specify incorrect data connection settings, you cannot update these settings on the same pipeline server. Therefore, you must delete the pipeline server and configure another one.

In the Database section, click Show advanced database options to specify the database to store your pipeline data and select one of the following sets of actions:
- Select Use default database stored on your cluster to deploy a MariaDB database in your project.
- Select Connect to external MySQL database to add a new connection to an external database that your pipeline server can access.
  1. In the Host field, enter the database’s host name.
  2. In the Port field, enter the database’s port.
  3. In the Username field, enter the default user name that is connected to the database.
  4. In the Password field, enter the password for the default user account.
  5. In the Database field, enter the database name.
Click Configure pipeline server.

Verification

In the Pipelines tab for the project:

The Import pipeline button is available.
When you click the action menu (⋮) and then click View pipeline server configuration, the pipeline server details are displayed.

Defining a pipeline

You can also use the Elyra JupyterLab extension to create and run data science pipelines within JupyterLab. For more information about the Elyra JupyterLab extension, see Elyra Documentation.

Additional resources

Importing a data science pipeline

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have compiled your pipeline with the Kubeflow compiler and you have access to the resulting YAML file.
If you are uploading your pipeline from a URL, the URL is publicly accessible.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that you want to import a pipeline to.
Click Import pipeline.
In the Import pipeline dialog, enter the details for the pipeline that you are importing.
1. In the Pipeline name field, enter a name for the pipeline that you are importing.
2. In the Pipeline description field, enter a description for the pipeline that you are importing.
3. Select where you want to import your pipeline from by performing one of the following actions:
  - Select Upload a file to upload your pipeline from your local machine’s file system. Import your pipeline by clicking upload or by dragging and dropping a file.
  - Select Import by url to upload your pipeline from a URL and then enter the URL into the text box.
4. Click Import pipeline.

Verification

The pipeline that you imported appears on the Pipelines page and on the Pipelines tab on the project details page.

Downloading a data science pipeline version

To make further changes to a data science pipeline version that you previously uploaded to Open Data Hub, you can download pipeline version code from the user interface.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have created and imported a pipeline to an active pipeline server that is available to download.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that contains the version that you want to download.
For a pipeline that contains the version that you want to download, click Expand ().
Click the pipeline version that you want to download.
On the Pipeline details page, click the YAML tab.
Click the Download button () to download the YAML file containing your pipeline version code to your local machine.

Verification

The pipeline version code downloads to your browser’s default directory for downloaded files.

Deleting a data science pipeline

If you no longer require access to your data science pipeline on the dashboard, you can delete it so that it does not appear on the Data Science Pipelines page.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
There are active pipelines available on the Pipelines page.
The pipeline that you want to delete does not contain any pipeline versions.
The pipeline that you want to delete does not contain any pipeline versions. For more information, see Deleting a pipeline version.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that contains the pipeline that you want to delete from the Project list.
Click the action menu (⋮) beside the pipeline that you want to delete and click Delete pipeline.
In the Delete pipeline dialog, enter the pipeline name in the text field to confirm that you intend to delete it.
Click Delete pipeline.

Verification

The data science pipeline that you deleted no longer appears on the Pipelines page.

Deleting a pipeline server

After you have finished running your data science pipelines, you can delete the pipeline server. Deleting a pipeline server automatically deletes all of its associated pipelines, pipeline versions, and runs. If your pipeline data is stored in a database, the database is also deleted along with its meta-data. In addition, after deleting a pipeline server, you cannot create new pipelines or pipeline runs until you create another pipeline server.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a pipeline server.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project for the pipeline server that you want to delete.
From the Pipeline server actions list, select Delete pipeline server.
In the Delete pipeline server dialog, enter the pipeline server’s name in the text field to confirm that you intend to delete it.
Click Delete.

Verification

Pipelines previously assigned to the deleted pipeline server no longer appears on the Pipelines page for the relevant data science project.
Pipeline runs previously assigned to the deleted pipeline server no longer appears on the Runs page for the relevant data science project.

Viewing the details of a pipeline server

You can view the details of pipeline servers configured in Open Data Hub, such as the pipeline’s data connection details and where its data is stored.

Prerequisites

You have logged in to Open Data Hub.
You have previously created a data science project that contains an active and available pipeline server.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page opens, select the project whose pipeline server you want to view.
From the Pipeline server actions list, select View pipeline server configuration.

Verification

You can view the relevant pipeline server details in the View pipeline server dialog.

Viewing existing pipelines

You can view the details of pipelines that you have imported to Open Data Hub, such as the pipeline’s last run, when it was created, the pipeline’s executed runs, and details of any associated pipeline versions.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a pipeline server.
You have imported a pipeline to an active pipeline server.
Existing pipelines are available.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the relevant project for the pipelines you want to view.
Study the pipelines on the list.
Optional: Click Expand () on the relevant row to view details of any pipeline versions associated with the pipeline.

Verification

A list of previously created data science pipelines appears on the Pipelines page.

Managing pipeline runs

Overview of pipeline runs

A pipeline run is a single execution of a data science pipeline. As data scientist, you can use Open Data Hub to define, manage, and track executions of a data science pipeline. You can view a record of previously executed, scheduled, and archived runs from the Runs page in the Open Data Hub user interface.

You can optimize your use of pipeline runs for portability. You can clone your pipeline runs to reproduce and scale them accordingly, or archive them when you want to retain a record of their execution, but no longer require them. You can delete archived runs that you no longer want to retain, or you can restore them to their former state.

You can execute a run once, that is, immediately after its creation, or on a recurring basis. Recurring runs consist of a copy of a pipeline with all of its parameter values and a run trigger. A run trigger indicates when a recurring run executes. You can define the following run triggers:

Periodic: used for scheduling runs to execute in intervals.
Cron: used for scheduling runs as a cron job.

You can also configure multiple instances of the same run to execute concurrently, from a range of one to ten. When executed, you can track the run’s progress from the run Details page on the Open Data Hub user interface. From here, you can view the run’s graph, and output artifacts. A pipeline run can be in one of the following states:

Scheduled run: A pipeline run scheduled to execute at least once.
Active run: A pipeline run that is in its execution phase, or is stopped.
Archived run: A pipeline run that resides in the run archive and is no longer required.

You can use catch up runs to ensure your pipeline runs do not permanently fall behind schedule when paused. For example, if you re-enable a paused recurring run, the run scheduler backfills each missed run interval. If you disable catch up runs, and you have a scheduled run interval ready to execute, the run scheduler only schedules the run execution for the latest run interval. Catch up runs are enabled by default. However, if your pipeline handles backfill internally, Red Hat recommends that you disable catch up runs to avoid duplicate backfill.

You can review and analyze logs for each step in an active pipeline run. With the log viewer, you can search for specific log messages, view the log for each step, and download the step logs to your local machine.

Viewing active pipeline runs

You can view a list of pipeline runs that were previously executed in Open Data Hub. From this list, you can view details relating to your pipeline runs, such as the pipeline version that the run belongs to, along with the run status, duration, and execution start time.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and has a pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously executed a pipeline run.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project for the active pipeline runs that you want to view.
On the Run details page, click the Active tab.

After a run has completed its execution, the run’s status appears in the Status column in the table, indicating whether the run has succeeded or failed.

Verification

A list of active runs appears in the Active tab on the Runs page.

Executing a pipeline run

You can instantiate a single execution of a pipeline by creating an active pipeline run that executes immediately after creation.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have imported a pipeline to an active pipeline server.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project that you want to create a run for.
Click Create run.
On the Create run page, configure the run:
1. In the Name field, enter a name for the run.
2. In the Description field, enter a description for the run.
3. From the Pipeline list, select the pipeline that you want to create a run for. Alternatively, to create a new pipeline, click Create new pipeline and complete the relevant fields in the Import pipeline dialog.
4. From the Pipeline version list, select the pipeline version to create a run for. Alternatively, to upload a new version, click Upload new version and complete the relevant fields in the Upload new version dialog.
5. Configure the input parameters for the run by selecting the parameters from the list.
6. Click Create run.

Verification

The pipeline run that you created appears in the Active tab on the Runs page.

Stopping an active pipeline run

If you no longer require an active pipeline run to continue executing, you can stop the run before its defined end date.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
There is a previously created data science project available that contains a pipeline server.
You have imported a pipeline to an active pipeline server.
An active pipeline run is currently executing.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project that contains the pipeline whose active run you want to stop.
In the Active tab, click the action menu (⋮) beside the active run that you want to delete and click Stop.

There might be a short delay while the run stops.

Verification

In the list of active runs, the status of the run is "stopped".

Duplicating an active pipeline run

To make it easier to quickly execute pipeline runs with the same configuration, you can duplicate them.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have imported a pipeline to an active pipeline server.
An active run is available to duplicate in the Active tab on the Runs page.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project that has the pipeline run that you want to duplicate.
Click the action menu (⋮) beside the relevant active run and click Duplicate.
In the Duplicate run page, configure the duplicate run:
1. In the Name field, enter a name for the duplicate run.
2. In the Description field, enter a description for the duplicate run.
3. From the Pipeline list, select the pipeline to contain the duplicate run.
4. From the Pipeline version list, select the pipeline version to contain the duplicate run.
5. In the Parameters section, configure the input parameters for the run that you are duplicating by selecting the appropriate parameters from the list.
6. Click Create run.

Verification

The duplicate pipeline run appears in the Active tab on the Runs page.

Viewing scheduled pipeline runs

You can view a list of pipeline runs that are scheduled for execution in Open Data Hub. From this list, you can view details relating to your pipeline runs, such as the pipeline version that the run belongs to. You can also view the run status, execution frequency, and schedule.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a pipeline server.
You have imported a pipeline to an active pipeline server.
You have scheduled a pipeline run that is available to view.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.

The Runs page opens.
From the Project list, select the project whose scheduled pipeline runs you want to view.
Click the Schedules tab.
Study the table showing a list of scheduled runs.

After a run has been scheduled, the run’s status indicates whether the run is ready for execution or unavailable for execution. To change its execution availability, click the run’s Status icon.

Verification

A list of scheduled runs appears in the Schedules tab on the Runs page.

Scheduling a pipeline run using a cron job

You can use a cron job to schedule a pipeline run to execute at a specific time. Cron jobs are useful for creating periodic and recurring tasks, and can also schedule individual tasks for a specific time, such as if you want to schedule a run for a low activity period. To successfully execute runs in Open Data Hub, you must use the supported format. See Cron Expression Format for more information.

The following examples show the correct format:

Run occurrence	Cron format
Every five minutes	@every 5m
Every 10 minutes	0 /10 * * *
Daily at 16:16 UTC	0 16 16 * * *
Daily every quarter of the hour	0 0,15,30,45 * * * *
On Monday and Tuesday at 15:40 UTC	0 40 15 * * MON,TUE

Run occurrence

Cron format

Every five minutes

@every 5m

Every 10 minutes

0 */10 * * * *

Daily at 16:16 UTC

0 16 16 * * *

Daily every quarter of the hour

0 0,15,30,45 * * * *

On Monday and Tuesday at 15:40 UTC

0 40 15 * * MON,TUE

Additional resources

Cron Expression Format

Scheduling a pipeline run

To repeatedly run a pipeline, you can create a scheduled pipeline run.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have imported a pipeline to an active pipeline server.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.

The Runs page opens.
From the Project list, select the project that you want to schedule a run for.
Click the Schedules tab.
Click Schedule run.
On the Schedule run page, configure the run that you are scheduling:
1. In the Name field, enter a name for the run.
2. In the Description field, enter a description for the run.
3. From the Trigger type list, select one of the following options:
  - Select Periodic to specify an execution frequency. In the Run every field, enter a numerical value and select an execution frequency from the list.
  - Select Cron to specify the execution schedule in cron format. This creates a cron job to execute the run. Click the Copy button () to copy the cron job schedule to the clipboard. The field furthest to the left represents seconds. For more information about scheduling tasks using the supported cron format, see Cron Expression Format.
4. In the Maximum concurrent runs field, specify the number of runs that can execute concurrently, from a range of one to ten.
5. For Start date, specify a start date for the run. Select a start date using the Calendar and the start time from the list of times.
6. For End date, specify an end date for the run. Select an end date using the Calendar and the end time from the list of times.
7. For Catch up, enable or disable catch up runs. You can use catch up runs to ensure your pipeline runs do not permanently fall behind schedule when paused. For example, if you re-enable a paused recurring run, the run scheduler backfills each missed run interval.
8. From the Pipeline list, select the pipeline that you want to create a run for. Alternatively, to create a new pipeline, click Create new pipeline and complete the relevant fields in the Import pipeline dialog.
9. From the Pipeline version list, select the pipeline version to create a run for. Alternatively, to upload a new version, click Upload new version and complete the relevant fields in the Upload new version dialog.
10. Configure the input parameters for the run by selecting the parameters from the list.
11. Click Schedule run.

Verification

The pipeline run that you created appears in the Schedules tab on the Runs page.

Duplicating a scheduled pipeline run

To make it easier to schedule runs to execute as part of your pipeline configuration, you can duplicate existing scheduled runs.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have imported a pipeline to an active pipeline server.
A scheduled run is available to duplicate in the Schedules tab on the Runs page.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project that has the pipeline run that you want to duplicate.
Click the Schedules tab.
Click the action menu (⋮) beside the run that you want to duplicate and click Duplicate.
On the Duplicate schedule page, configure the duplicate run:
1. In the Name field, enter a name for the duplicate run.
2. In the Description field, enter a description for the duplicate run.
3. From the Trigger type list, select one of the following options:
  - Select Periodic to specify an execution frequency. In the Run every field, enter a numerical value and select an execution frequency from the list.
  - Select Cron to specify the execution schedule in cron format. This creates a cron job to execute the run. Click the Copy button () to copy the cron job schedule to the clipboard. The field furthest to the left represents seconds. For more information about scheduling tasks using the supported cron format, see Cron Expression Format.
4. For Maximum concurrent runs, specify the number of runs that can execute concurrently, from a range of one to ten.
5. For Start date, specify a start date for the duplicate run. Select a start date using the Calendar and the start time from the list of times.
6. For End date, specify an end date for the duplicate run. Select an end date using the Calendar and the end time from the list of times.
7. For Catch up, enable or disable catch up runs. You can use catch up runs to ensure your pipeline runs do not permanently fall behind schedule when paused. For example, if you re-enable a paused recurring run, the run scheduler backfills each missed run interval.
8. From the Pipeline list, select the pipeline that you want to create a duplicate run for. Alternatively, to create a new pipeline, click Create new pipeline and complete the relevant fields in the Import pipeline dialog.
9. From the Pipeline version list, select the pipeline version to create a duplicate run for. Alternatively, to upload a new version, click Upload new version and complete the relevant fields in the Upload new version dialog.
10. Configure the input parameters for the run by selecting the parameters from the list.
11. Click Schedule run.

Verification

The pipeline run that you duplicated appears in the Schedules tab on the Runs page.

Deleting a scheduled pipeline run

To discard pipeline runs that you previously scheduled, but no longer require, you can delete them so that they do not appear on the Runs page.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously scheduled a run that is available to delete.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.

The Runs page opens.
From the Project list, select the project that contains the pipeline whose scheduled run you want to delete.

The page refreshes to show the pipeline’s scheduled runs on the Schedules tab.
Click the action menu (⋮) beside the scheduled run that you want to delete and click Delete.

The Delete schedule dialog opens.
Enter the run’s name in the text field to confirm that you intend to delete it.
Click Delete.

Verification

The run that you deleted no longer appears on the Schedules tab.

Viewing the details of a pipeline run

To gain a clearer understanding of your pipeline runs, you can view the details of a previously triggered pipeline run, such as its graph, execution details, and run output.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously triggered a pipeline run.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that you want to view run details for.
For a pipeline that you want to view run details for, click Expand ().
Click the action menu (⋮) for the pipeline version and then click View runs.
On the Runs page, click the name of the run that you want to view the details of.

Verification

On the Run details page, you can view the run’s graph, execution details, input parameters, step logs, and run output.

Viewing archived pipeline runs

You can view a list of pipeline runs that you have archived. You can view details for your archived pipeline runs, such as the pipeline version, run status, duration, and execution start date.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and has a pipeline server.
You have imported a pipeline to an active pipeline server.
An archived pipeline run exists.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project for the archived pipeline runs that you want to view.
Click the Archived tab.

Verification

A list of archived runs appears in the Archived tab on the Runs page.

Archiving a pipeline run

You can retain records of your pipeline runs by archiving them. If required, you can restore runs from your archive to reuse, or delete runs that are no longer required.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and has a pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously executed a pipeline run that is available.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project for the pipeline run that you want to archive from the Project list.
On the Run details page, click the action menu (⋮) beside the run that you want to archive and then click Archive.
In the Archiving run dialog, enter the run name in the text field to confirm that you intend to archive it.
Click Archive.

Verification

The archived run does not appear in the Active tab and instead appears in the Archived tab on the Runs page.

Restoring an archived pipeline run

You can restore an archived run to the active state.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and has a pipeline server.
You have imported a pipeline to an active pipeline server.
An archived run exists in your project.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project for the archived pipeline run that you want to restore.
On the Run details page, click the Archived tab.
Click the action menu (⋮) beside the run that you want to restore and click Restore.
In the Restore run dialog, enter the run name in the text field to confirm that you intend to restore it.
Click Restore.

Verification

The restored run appears in the Active tab on the Runs page.

Deleting an archived pipeline run

You can delete pipeline runs from the Open Data Hub run archive.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and has a pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously archived a pipeline run.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project for the archived pipeline run you want to delete.
In the Run details page, click Archived.
Click the action menu (⋮) beside the run that you want to delete and click Delete.
In the Delete run dialog, enter the run name in the text field to confirm that you intend to delete it.
Click Delete.

Verification

The archived run that you deleted no longer appears in the Archived tab on the Runs page.

Duplicating an archived pipeline run

To make it easier to reproduce runs with the same configuration as runs in your archive, you can duplicate them.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a configured pipeline server.
You have imported a pipeline to an active pipeline server.
An archived run is available to duplicate in the Archived tab on the Runs page.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Runs.
On the Runs page, select the project that has the pipeline run that you want to duplicate.
Click the Archived tab.
Click the action menu (⋮) beside the relevant archived run and click Duplicate.
On the Duplicate run page, configure the duplicate run:
1. In the Name field, enter a name for the duplicate run.
2. In the Description field, enter a description for the duplicate run.
3. From the Pipeline list, select the pipeline to contain the duplicate run.
4. From the Pipeline version list, select the pipeline version to contain the duplicate run.
5. In the Parameters section, configure the input parameters for the run that you are duplicating by selecting the appropriate parameters from the list.
6. Click Create run.

Verification

The duplicate pipeline run appears in the Active tab on the Runs page.

Working with pipeline logs

About pipeline logs

You can review and analyze step logs for each step in a triggered pipeline run.

To help you troubleshoot and audit your pipelines, you can review and analyze these step logs by using the log viewer in the Open Data Hub dashboard. From here, you can search for specific log messages, view the log for each step, and download the step logs to your local machine.

If the step log file exceeds its capacity, a warning appears above the log viewer stating that the log window displays partial content. Expanding the warning displays further information, such as how the log viewer refreshes every three seconds, and that each step log displays the last 500 lines of log messages received. In addition, you can click download all step logs to download all step logs to your local machine.

Each step has a set of container logs. You can view these container logs by selecting a container from the Steps list in the log viewer. The Step-main container log consists of the log output for the step. The step-copy-artifact container log consists of output relating to artifact data sent to s3-compatible storage. If the data transferred between the steps in your pipeline is larger than 3 KB, five container logs are typically available. These logs contain output relating to data transferred between your persistent volume claims (PVCs).

Viewing pipeline step logs

To help you troubleshoot and audit your pipelines, you can review and analyze the log of each pipeline step using the log viewer. From here, you can search for specific log messages and download the logs for each step in your pipeline. If the pipeline is running, you can also pause and resume the log from the log viewer.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously triggered a pipeline run.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that you want to view logs for.
For the pipeline that you want to view logs for, click Expand ().
Click the action menu (⋮) on the row containing the project version that you want to view pipeline logs for and click View runs.
On the Runs page, click the name of the run that you want to view logs for.
On the graph on the Run details page , click the pipeline step that you want to view logs for.
Click the Logs tab.
To view the logs of another pipeline step, from the Steps list, select the step that you want to view logs for.
Analyze the log using the log viewer.
- To search for a specific log message, enter at least part of the message in the search bar.
- To view the full log in a separate browser window, click the action menu (⋮) and select View raw logs. Alternatively, to expand the size of the log viewer, click the action menu (⋮) and select Expand.

Verification

You can view the logs for each step in your pipeline.

Downloading pipeline step logs

Instead of viewing the step logs of a pipeline run using the log viewer on the Open Data Hub dashboard, you can download them for further analysis. You can choose to download the logs belonging to all steps in your pipeline, or you can download the log only for the step log displayed in the log viewer.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have previously created a data science project that is available and contains a pipeline server.
You have imported a pipeline to an active pipeline server.
You have previously triggered a pipeline run.

Procedure

From the Open Data Hub dashboard, click Data Science Pipelines → Pipelines.
On the Pipelines page, select the project that you want to download logs for.
For the pipeline that you want to download logs for, click Expand ().
Click View runs on the row containing the pipeline version that you want to download logs for.
On the Runs page, click the name of the run that you want to download logs for.
On the graph on the Run details page, click the pipeline step that you want to download logs for.
Click the Logs tab.
In the log viewer, click the Download button ().
1. Select Download current stop log to download the log for the current pipeline step.
2. Select Download all step logs to download the logs for all steps in your pipeline run.

Verification

The step logs download to your browser’s default directory for downloaded files.

Working with pipelines in JupyterLab

Overview of pipelines in JupyterLab

You can use Elyra to create visual end-to-end pipeline workflows in JupyterLab. Elyra is an extension for JupyterLab that provides you with a Pipeline Editor to create pipeline workflows that can be executed in Open Data Hub.

You can access the Elyra extension within JupyterLab when you create the most recent version of one of the following notebook images:

Standard Data Science
PyTorch
TensorFlow
TrustyAI
HabanaAI

When you use the Pipeline Editor to visually design your pipelines, minimal coding is required to create and run pipelines. For more information about Elyra, see Elyra Documentation. For more information about the Pipeline Editor, see Visual Pipeline Editor. After you have created your pipeline, you can run it locally in JupyterLab, or remotely using data science pipelines in Open Data Hub.

The pipeline creation process consists of the following tasks:

Create a data science project that contains a workbench.
Create a pipeline server.
Create a new pipeline in the Pipeline Editor in JupyterLab.
Develop your pipeline by adding Python notebooks or Python scripts and defining their runtime properties.
Define execution dependencies.
Run or export your pipeline.

Before you can run a pipeline in JupyterLab, your pipeline instance must contain a runtime configuration. A runtime configuration defines connectivity information for your pipeline instance and S3-compatible cloud storage.

If you create a workbench as part of a data science project, a default runtime configuration is created automatically. However, if you create a notebook from the Jupyter tile in the Open Data Hub dashboard, you must create a runtime configuration before you can run your pipeline in JupyterLab. For more information about runtime configurations, see Runtime Configuration. As a prerequisite, before you create a workbench, ensure that you have created and configured a pipeline server within the same data science project as your workbench.

You can use S3-compatible cloud storage to make data available to your notebooks and scripts while they are executed. Your cloud storage must be accessible from the machine in your deployment that runs JupyterLab and from the cluster that hosts Data Science Pipelines. Before you create and run pipelines in JupyterLab, ensure that you have your s3-compatible storage credentials readily available.

Additional resources

Accessing the pipeline editor

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project.
You have created a workbench with the Standard Data Science notebook image.
You have created and configured a pipeline server within the data science project that contains your workbench.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).
You have access to S3-compatible storage.

Procedure

After you open JupyterLab, confirm that the JupyterLab launcher is automatically displayed.
In the Elyra section of the JupyterLab launcher, click the Pipeline Editor tile.

The Pipeline Editor opens.

Verification

You can view the Pipeline Editor in JupyterLab.

Creating a runtime configuration

If you create a workbench as part of a data science project, a default runtime configuration is created automatically. However, if you create a notebook from the Jupyter tile in the Open Data Hub dashboard, you must create a runtime configuration before you can run your pipeline in JupyterLab. This enables you to specify connectivity information for your pipeline instance and S3-compatible cloud storage.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have access to S3-compatible cloud storage.
You have created a data science project that contains a workbench.
You have created and configured a pipeline server within the data science project that contains your workbench.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).

Procedure

In the left sidebar of JupyterLab, click Runtimes ().
Click the Create new runtime configuration button ().

The Add new Data Science Pipelines runtime configuration page opens.

Complete the relevant fields to define your runtime configuration.

In the Display Name field, enter a name for your runtime configuration.
Optional: In the Description field, enter a description to define your runtime configuration.
Optional: In the Tags field, click Add Tag to define a category for your pipeline instance. Enter a name for the tag and press Enter.

Define the credentials of your data science pipeline:

In the Data Science Pipelines API Endpoint field, enter the API endpoint of your data science pipeline. Do not specify the pipelines namespace in this field.

In the Public Data Science Pipelines API Endpoint field, enter the public API endpoint of your data science pipeline.

Important

You can obtain the Data Science Pipelines API endpoint from the Data Science Pipelines → Runs page in the dashboard. Copy the relevant end point and enter it in the Public Data Science Pipelines API Endpoint field.

Optional: In the Data Science Pipelines User Namespace field, enter the relevant user namespace to run pipelines.
From the Authentication Type list, select the authentication type required to authenticate your pipeline.

Important

If you created a notebook directly from the Jupyter tile on the dashboard, select EXISTING_BEARER_TOKEN from the Authentication Type list.
In the Data Science Pipelines API Endpoint Username field, enter the user name required for the authentication type.

In the Data Science Pipelines API Endpoint Password Or Token, enter the password or token required for the authentication type.

Important

To obtain the Data Science Pipelines API endpoint token, in the upper-right corner of the OpenShift web console, click your user name and select Copy login command. After you have logged in, click Display token and copy the value of --token= from the Log in with this token command.

Define the connectivity information of your S3-compatible storage:
1. In the Cloud Object Storage Endpoint field, enter the endpoint of your S3-compatible storage. For more information about Amazon s3 endpoints, see Amazon Simple Storage Service endpoints and quotas.
2. Optional: In the Public Cloud Object Storage Endpoint field, enter the URL of your S3-compatible storage.
3. In the Cloud Object Storage Bucket Name field, enter the name of the bucket where your pipeline artifacts are stored. If the bucket name does not exist, it is created automatically.
4. From the Cloud Object Storage Authentication Type list, select the authentication type required to access to your S3-compatible cloud storage. If you use AWS S3 buckets, select KUBERNETES_SECRET from the list.
5. In the Cloud Object Storage Credentials Secret field, enter the secret that contains the storage user name and password. This secret is defined in the relevant user namespace, if applicable. In addition, it must be stored on the cluster that hosts your pipeline runtime.
6. In the Cloud Object Storage Username field, enter the user name to connect to your S3-compatible cloud storage, if applicable. If you use AWS S3 buckets, enter your AWS Secret Access Key ID.
7. In the Cloud Object Storage Password field, enter the password to connect to your S3-compatible cloud storage, if applicable. If you use AWS S3 buckets, enter your AWS Secret Access Key.
Click Save & Close.

Verification

The runtime configuration that you created is shown in the Runtimes tab () in the left sidebar of JupyterLab.

Updating a runtime configuration

To ensure that your runtime configuration is accurate and updated, you can change the settings of an existing runtime configuration.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have access to S3-compatible storage.
You have created a data science project that contains a workbench.
You have created and configured a pipeline server within the data science project that contains your workbench.
A previously created runtime configuration is available in the JupyterLab interface.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).

Procedure

In the left sidebar of JupyterLab, click Runtimes ().
Hover the cursor over the runtime configuration that you want to update and click the Edit button ().

The Data Science Pipelines runtime configuration page opens.

Fill in the relevant fields to update your runtime configuration.

In the Display Name field, update name for your runtime configuration, if applicable.
Optional: In the Description field, update the description of your runtime configuration, if applicable.
Optional: In the Tags field, click Add Tag to define a category for your pipeline instance. Enter a name for the tag and press Enter.

Define the credentials of your data science pipeline:

In the Data Science Pipelines API Endpoint field, update the API endpoint of your data science pipeline, if applicable. Do not specify the pipelines namespace in this field.
In the Public Data Science Pipelines API Endpoint field, update the API endpoint of your data science pipeline, if applicable.
Optional: In the Data Science Pipelines User Namespace field, update the relevant user namespace to run pipelines, if applicable.
From the Authentication Type list, select a new authentication type required to authenticate your pipeline, if applicable.

Important

If you created a notebook directly from the Jupyter tile on the dashboard, select EXISTING_BEARER_TOKEN from the Authentication Type list.
In the Data Science Pipelines API Endpoint Username field, update the user name required for the authentication type, if applicable.

In the Data Science Pipelines API Endpoint Password Or Token, update the password or token required for the authentication type, if applicable.

Important

Define the connectivity information of your S3-compatible storage:
1. In the Cloud Object Storage Endpoint field, update the endpoint of your S3-compatible storage, if applicable. For more information about Amazon s3 endpoints, see Amazon Simple Storage Service endpoints and quotas.
2. Optional: In the Public Cloud Object Storage Endpoint field, update the URL of your S3-compatible storage, if applicable.
3. In the Cloud Object Storage Bucket Name field, update the name of the bucket where your pipeline artifacts are stored, if applicable. If the bucket name does not exist, it is created automatically.
4. From the Cloud Object Storage Authentication Type list, update the authentication type required to access to your S3-compatible cloud storage, if applicable. If you use AWS S3 buckets, you must select USER_CREDENTIALS from the list.
5. Optional: In the Cloud Object Storage Credentials Secret field, update the secret that contains the storage user name and password, if applicable. This secret is defined in the relevant user namespace. You must save the secret on the cluster that hosts your pipeline runtime.
6. Optional: In the Cloud Object Storage Username field, update the user name to connect to your S3-compatible cloud storage, if applicable. If you use AWS S3 buckets, update your AWS Secret Access Key ID.
7. Optional: In the Cloud Object Storage Password field, update the password to connect to your S3-compatible cloud storage, if applicable. If you use AWS S3 buckets, update your AWS Secret Access Key.
Click Save & Close.

Verification

The runtime configuration that you updated is shown in the Runtimes tab () in the left sidebar of JupyterLab.

Deleting a runtime configuration

After you have finished using your runtime configuration, you can delete it from the JupyterLab interface. After deleting a runtime configuration, you cannot run pipelines in JupyterLab until you create another runtime configuration.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that contains a workbench.
You have created and configured a pipeline server within the data science project that contains your workbench.
A previously created runtime configuration is visible in the JupyterLab interface.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).

Procedure

In the left sidebar of JupyterLab, click Runtimes ().
Hover the cursor over the runtime configuration that you want to delete and click the Delete Item button ().

A dialog box appears prompting you to confirm the deletion of your runtime configuration.
Click OK.

Verification

The runtime configuration that you deleted is no longer shown in the Runtimes tab () in the left sidebar of JupyterLab.

Duplicating a runtime configuration

To prevent you from re-creating runtime configurations with similar values in their entirety, you can duplicate an existing runtime configuration in the JupyterLab interface.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that contains a workbench.
You have created and configured a pipeline server within the data science project that contains your workbench.
A previously created runtime configuration is visible in the JupyterLab interface.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).

Procedure

In the left sidebar of JupyterLab, click Runtimes ().
Hover the cursor over the runtime configuration that you want to duplicate and click the Duplicate button ().

Verification

The runtime configuration that you duplicated is shown in the Runtimes tab () in the left sidebar of JupyterLab.

Running a pipeline in JupyterLab

You can run pipelines that you have created in JupyterLab from the Pipeline Editor user interface. Before you can run a pipeline, you must create a data science project and a pipeline server. After you create a pipeline server, you must create a workbench within the same project as your pipeline server. Your pipeline instance in JupyterLab must contain a runtime configuration. If you create a workbench as part of a data science project, a default runtime configuration is created automatically. However, if you create a notebook from the Jupyter tile in the Open Data Hub dashboard, you must create a runtime configuration before you can run your pipeline in JupyterLab. A runtime configuration defines connectivity information for your pipeline instance and S3-compatible cloud storage.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have access to S3-compatible storage.
You have created a pipeline in JupyterLab.
You have opened your pipeline in the Pipeline Editor in JupyterLab.
Your pipeline instance contains a runtime configuration.
You have created and configured a pipeline server within the data science project that contains your workbench.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).

Procedure

In the Pipeline Editor user interface, click Run Pipeline ().

The Run Pipeline dialog appears. The Pipeline Name field is automatically populated with the pipeline file name.

Important

You must enter a unique pipeline name. The pipeline name that you enter must not match the name of any previously executed pipelines.
Define the settings for your pipeline run.
1. From the Runtime Configuration list, select the relevant runtime configuration to run your pipeline.
2. Optional: Configure your pipeline parameters, if applicable. If your pipeline contains nodes that reference pipeline parameters, you can change the default parameter values. If a parameter is required and has no default value, you must enter a value.
Click OK.

Verification

You can view the output artifacts of your pipeline run. The artifacts are stored in your designated object storage bucket.

Exporting a pipeline in JupyterLab

You can export pipelines that you have created in JupyterLab. When you export a pipeline, the pipeline is prepared for later execution, but is not uploaded or executed immediately. During the export process, any package dependencies are uploaded to S3-compatible storage. Also, pipeline code is generated for the target runtime.

Before you can export a pipeline, you must create a data science project and a pipeline server. After you create a pipeline server, you must create a workbench within the same project as your pipeline server. In addition, your pipeline instance in JupyterLab must contain a runtime configuration. If you create a workbench as part of a data science project, a default runtime configuration is created automatically. However, if you create a notebook from the Jupyter tile in the Open Data Hub dashboard, you must create a runtime configuration before you can export your pipeline in JupyterLab. A runtime configuration defines connectivity information for your pipeline instance and S3-compatible cloud storage.

Prerequisites

You have logged in to Open Data Hub.
If you are using specialized Open Data Hub groups, you are part of the user group or admin group (for example, odh-users or odh-admins) in OpenShift.
You have created a data science project that contains a workbench.
You have created and configured a pipeline server within the data science project that contains your workbench.
You have access to S3-compatible storage.
You have a created a pipeline in JupyterLab.
You have opened your pipeline in the Pipeline Editor in JupyterLab.
Your pipeline instance contains a runtime configuration.
You have created and launched a Jupyter server from a notebook image that contains the Elyra extension (Standard data science, TensorFlow, TrustyAI, PyTorch, or HabanaAI).

Procedure

In the Pipeline Editor user interface, click Export Pipeline ().

The Export Pipeline dialog appears. The Pipeline Name field is automatically populated with the pipeline file name.
Define the settings to export your pipeline.
1. From the Runtime Configuration list, select the relevant runtime configuration to export your pipeline.
2. From the Export Pipeline as select an appropriate file format
3. In the Export Filename field, enter a file name for the exported pipeline.
4. Select the Replace if file already exists check box to replace an existing file of the same name as the pipeline you are exporting.
5. Optional: Configure your pipeline parameters, if applicable. If your pipeline contains nodes that reference pipeline parameters, you can change the default parameter values. If a parameter is required and has no default value, you must enter a value.
Click OK.

Verification

You can view the file containing the pipeline that you exported in your designated object storage bucket.

Additional resources

Working with accelerators

Use accelerators, such as NVIDIA GPUs and Habana Gaudi devices, to optimize the performance of your end-to-end data science workflows.

Overview of accelerators

If you work with large data sets, you can use accelerators to optimize the performance of your data science models in Open Data Hub. With accelerators, you can scale your work, reduce latency, and increase productivity. You can use accelerators in Open Data Hub to assist your data scientists in the following tasks:

Natural language processing (NLP)
Inference
Training deep neural networks
Data cleansing and data processing

Open Data Hub supports the following accelerators:

NVIDIA graphics processing units (GPUs)
- To use compute-heavy workloads in your models, you can enable NVIDIA graphics processing units (GPUs) in Open Data Hub.
- To enable GPUs on OpenShift, you must install the NVIDIA GPU Operator.
Habana Gaudi devices (HPUs)
- Habana, an Intel company, provides hardware accelerators intended for deep learning workloads. You can use the Habana libraries and software associated with Habana Gaudi devices available from your notebook.
- Before you can enable Habana Gaudi devices in Open Data Hub, you must install the necessary dependencies and the version of the HabanaAI Operator that matches the Habana version of the HabanaAI workbench image in your deployment. For more information about how to enable your OpenShift environment for Habana Gaudi devices, see HabanaAI Operator v1.10 for OpenShift and HabanaAI Operator v1.13 for OpenShift.
- You can enable Habana Gaudi devices on-premises or with AWS DL1 compute nodes on an AWS instance.

Before you can use an accelerator in Open Data Hub, your OpenShift instance must contain an associated accelerator profile. For accelerators that are new to your deployment, you must configure an accelerator profile for the accelerator in context. You can create an accelerator profile from the Settings → Accelerator profiles page on the Open Data Hub dashboard. If your deployment contains existing accelerators that had associated accelerator profiles already configured, an accelerator profile is automatically created after you upgrade to the latest version of Open Data Hub.

Additional resources

Working with accelerator profiles

To configure accelerators for your data scientists to use in Open Data Hub, you must create an associated accelerator profile. An accelerator profile is a custom resource definition (CRD) on OpenShift that has an AcceleratorProfile resource, and defines the specification of the accelerator. You can create and manage accelerator profiles by selecting Settings → Accelerator profiles on the Open Data Hub dashboard.

For accelerators that are new to your deployment, you must manually configure an accelerator profile for each accelerator. If your deployment contains an accelerator before you upgrade, the associated accelerator profile remains after the upgrade. You can manage the accelerators that appear to your data scientists by assigning specific accelerator profiles to your custom notebook images. This example shows the code for a Habana Gaudi 1 accelerator profile:

---
apiVersion: dashboard.opendatahub.io/v1alpha
kind: AcceleratorProfile
metadata:
  name: hpu-profile-first-gen-gaudi
spec:
  displayName: Habana HPU - 1st Gen Gaudi
  description: First Generation Habana Gaudi device
  enabled: true
  identifier: habana.ai/gaudi
  tolerations:
    - effect: NoSchedule
      key: habana.ai/gaudi
      operator: Exists
---

The accelerator profile code appears on the Instances tab on the details page for the AcceleratorProfile custom resource definition (CRD). For more information about accelerator profile attributes, see the following table:

Table 2. Accelerator profile attributes
Attribute	Type	Required	Description
displayName	String	Required	The display name of the accelerator profile.
description	String	Optional	Descriptive text defining the accelerator profile.
identifier	String	Required	A unique identifier defining the accelerator resource.
enabled	Boolean	Required	Determines if the accelerator is visible in Open Data Hub.
tolerations	Array	Optional	The tolerations that can apply to notebooks and serving runtimes that use the accelerator. For more information about the toleration attributes that Open Data Hub supports, see Toleration v1 core.

Additional resources

Creating an accelerator profile

To configure accelerators for your data scientists to use in Open Data Hub, you must create an associated accelerator profile.

Prerequisites

You have logged in to Open Data Hub.

Procedure

From the Open Data Hub dashboard, click Settings → Accelerator profiles.

The Accelerator profiles page appears, displaying existing accelerator profiles. To enable or disable an existing accelerator profile, on the row containing the relevant accelerator profile, click the toggle in the Enable column.
Click Create accelerator profile.

The Create accelerator profile dialog appears.
In the Name field, enter a name for the accelerator profile.
In the Identifier field, enter a unique string that identifies the hardware accelerator associated with the accelerator profile.
Optional: In the Description field, enter a description for the accelerator profile.
To enable or disable the accelerator profile immediately after creation, click the toggle in the Enable column.
Optional: Add a toleration to schedule pods with matching taints.
1. Click Add toleration.
  
  The Add toleration dialog opens.
2. From the Operator list, select one of the following options:
  - Equal - The key/value/effect parameters must match. This is the default.
  - Exists - The key/effect parameters must match. You must leave a blank value parameter, which matches any.
3. From the Effect list, select one of the following options:
  - None
  - NoSchedule - New pods that do not match the taint are not scheduled onto that node. Existing pods on the node remain.
  - PreferNoSchedule - New pods that do not match the taint might be scheduled onto that node, but the scheduler tries not to. Existing pods on the node remain.
  - NoExecute - New pods that do not match the taint cannot be scheduled onto that node. Existing pods on the node that do not have a matching toleration are removed.
4. In the Key field, enter a toleration key. The key is any string, up to 253 characters. The key must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.
5. In the Value field, enter a toleration value. The value is any string, up to 63 characters. The value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.
6. In the Toleration Seconds section, select one of the following options to specify how long a pod stays bound to a node that has a node condition.
  - Forever - Pods stays permanently bound to a node.
  - Custom value - Enter a value, in seconds, to define how long pods stay bound to a node that has a node condition.
7. Click Add.
Click Create accelerator profile.

Verification

The accelerator profile appears on the Accelerator profiles page.
The Accelerator list appears on the Start a notebook server page. After you select an accelerator, the Number of accelerators field appears, which you can use to choose the number of accelerators for your notebook server.
The accelerator profile appears on the Instances tab on the details page for the AcceleratorProfile custom resource definition (CRD).

Additional resources

Updating an accelerator profile

You can update the existing accelerator profiles in your deployment. You might want to change important identifying information, such as the display name, the identifier, or the description.

Prerequisites

You have logged in to Open Data Hub.
The accelerator profile exists in your deployment.

Procedure

From the Open Data Hub dashboard, click Settings → Notebook images.

The Notebook images page appears. Previously imported notebook images are displayed. To enable or disable a previously imported notebook image, on the row containing the relevant notebook image, click the toggle in the Enable column.
Click the action menu (⋮) and select Edit from the list.

The Edit accelerator profile dialog opens.
In the Name field, update the accelerator profile name.
In the Identifier field, update the unique string that identifies the hardware accelerator associated with the accelerator profile, if applicable.
Optional: In the Description field, update the accelerator profile.
To enable or disable the accelerator profile immediately after creation, click the toggle in the Enable column.
Optional: Add a toleration to schedule pods with matching taints.
1. Click Add toleration.
  
  The Add toleration dialog opens.
2. From the Operator list, select one of the following options:
  - Equal - The key/value/effect parameters must match. This is the default.
  - Exists - The key/effect parameters must match. You must leave a blank value parameter, which matches any.
3. From the Effect list, select one of the following options:
  - None
  - NoSchedule - New pods that do not match the taint are not scheduled onto that node. Existing pods on the node remain.
  - PreferNoSchedule - New pods that do not match the taint might be scheduled onto that node, but the scheduler tries not to. Existing pods on the node remain.
  - NoExecute - New pods that do not match the taint cannot be scheduled onto that node. Existing pods on the node that do not have a matching toleration are removed.
4. In the Key field, enter a toleration key. The key is any string, up to 253 characters. The key must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.
5. In the Value field, enter a toleration value. The value is any string, up to 63 characters. The value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.
6. In the Toleration Seconds section, select one of the following options to specify how long a pod stays bound to a node that has a node condition.
  - Forever - Pods stays permanently bound to a node.
  - Custom value - Enter a value, in seconds, to define how long pods stay bound to a node that has a node condition.
7. Click Add.
If your accelerator profile contains existing tolerations, you can edit them.
1. Click the action menu (⋮) on the row containing the toleration that you want to edit and select Edit from the list.
2. Complete the applicable fields to update the details of the toleration.
3. Click Update.
Click Update accelerator profile.

Verification

If your accelerator profile has new identifying information, this information appears in the Accelerator list on the Start a notebook server page.

Additional resources

Deleting an accelerator profile

To discard accelerator profiles that you no longer require, you can delete them so that they do not appear on the dashboard.

Prerequisites

You have logged in to Open Data Hub.
The accelerator profile that you want to delete exists in your deployment.

Procedure

From the Open Data Hub dashboard, click Settings → Accelerator profiles.

The Accelerator profiles page appears, displaying existing accelerator profiles.
Click the action menu (⋮) beside the accelerator profile that you want to delete and click Delete.

The Delete accelerator profile dialog opens.
Enter the name of the accelerator profile in the text field to confirm that you intend to delete it.
Click Delete.

Verification

The accelerator profile no longer appears on the Accelerator profiles page.

Additional resources

Viewing accelerator profiles

If you have defined accelerator profiles for Open Data Hub, you can view, enable, and disable them from the Accelerator profiles page.

Prerequisites

You have logged in to Open Data Hub.
Your deployment contains existing accelerator profiles.

Procedure

From the Open Data Hub dashboard, click Settings → Accelerator profiles.

The Accelerator profiles page appears, displaying existing accelerator profiles.
Inspect the list of accelerator profiles. To enable or disable an accelerator profile, on the row containing the accelerator profile, click the toggle in the Enable column.

Verification

The Accelerator profiles page appears appears, displaying existing accelerator profiles.

Configuring a recommended accelerator for notebook images

To help you indicate the most suitable accelerators to your data scientists, you can configure a recommended tag to appear on the dashboard.

Prerequisites

You have logged in to OpenShift Container Platform.
You have the cluster-admin role in OpenShift Container Platform.
You have existing notebook images in your deployment.

Procedure

From the Open Data Hub dashboard, click Settings → Notebook images.

The Notebook images page appears. Previously imported notebook images are displayed.
Click the action menu (⋮) and select Edit from the list.

The Update notebook image dialog opens.
From the Accelerator identifier list, select an identifier to set its accelerator as recommended with the notebook image. If the notebook image contains only one accelerator identifier, the identifier name displays by default.

Click Update.

Note

If you have already configured an accelerator identifier for a notebook image, you can specify a recommended accelerator for the notebook image by creating an associated accelerator profile. To do this, click Create profile on the row containing the notebook image and complete the relevant fields. If the notebook image does not contain an accelerator identifier, you must manually configure one before creating an associated accelerator profile.

Verification

When your data scientists select an accelerator with a specific notebook image, a tag appears next to the corresponding accelerator indicating its compatibility.

Configuring a recommended accelerator for serving runtimes

To help you indicate the most suitable accelerators to your data scientists, you can configure a recommended accelerator tag for your serving runtimes.

Prerequisites

You have logged in to Open Data Hub.
If you use specialized Open Data Hub groups, you are part of the admin group (for example, odh-admins) in OpenShift.

Procedure

From the Open Data Hub dashboard, click Settings > Serving runtimes.

The Serving runtimes page opens and shows the model-serving runtimes that are already installed and enabled in your Open Data Hub deployment. By default, the OpenVINO Model Server runtime is pre-installed and enabled in Open Data Hub.

Edit your custom runtime that you want to add the recommended accelerator tag to, click the action menu (⋮) and select Edit.

A page with an embedded YAML editor opens.

Note

You cannot directly edit the OpenVINO Model Server runtime that is included in Open Data Hub by default. However, you can clone this runtime and edit the cloned version. You can then add the edited clone as a new, custom runtime. To do this, click the action menu beside the OpenVINO Model Server and select Duplicate.

In the editor, enter the YAML code to apply the annotation opendatahub.io/recommended-accelerators. The excerpt in this example shows the annotation to set a recommended tag for an NVIDIA GPU accelerator:
```
metadata:
	annotations:
		opendatahub.io/recommended-accelerators: '["nvidia.com/gpu"]'
```
Click Update.

Verification

When your data scientists select an accelerator with a specific serving runtime, a tag appears next to the corresponding accelerator indicating its compatibility.

Habana Gaudi integration

To accelerate your high-performance deep learning (DL) models, you can integrate Habana Gaudi devices in Open Data Hub. Open Data Hub also includes the HabanaAI workbench image, which is pre-built and ready for your data scientists to use after you install or upgrade Open Data Hub.

Before you can enable Habana Gaudi devices in Open Data Hub, you must install the necessary dependencies and the version of the HabanaAI Operator that matches the Habana version of the HabanaAI workbench image in your deployment. This allows your data scientists to use Habana libraries and software associated with Habana Gaudi devices from their workbench.

For more information about how to enable your OpenShift environment for Habana Gaudi devices, see HabanaAI Operator v1.10 for OpenShift and HabanaAI Operator v1.13 for OpenShift.

Important

Currently, Habana Gaudi integration is only supported in OpenShift 4.12.

You can use Habana Gaudi accelerators on Open Data Hub with versions 1.10.0 and 1.13.0 of the Habana Gaudi Operator. The version of the HabanaAI Operator that you install must match the Habana version of the HabanaAI workbench image in your deployment. This means that only one version of HabanaAI workbench image will work for you at a time.

For information about the supported configurations for versions 1.10 and 1.13 of the Habana Gaudi Operator, see Support Matrix v1.10.0 and Support Matrix v1.13.0.

You can use Habana Gaudi devices in an Amazon EC2 DL1 instance on OpenShift. Therefore, your OpenShift platform must support EC2 DL1 instances. Habana Gaudi accelerators are available to your data scientists when they create a workbench instance or serve a model.

To identify the Habana Gaudi devices present in your deployment, use the lspci utility. For more information, see lspci(8) - Linux man page.

Important

If the lspci utility indicates that Habana Gaudi devices are present in your deployment, it does not necessarily mean that the devices are ready to use.

Before you can use your Habana Gaudi devices, you must enable them in your OpenShift environment and configure an accelerator profile for each device. For more information about how to enable your OpenShift environment for Habana Gaudi devices, see HabanaAI Operator for OpenShift.

Additional resources

Enabling Habana Gaudi devices

Before you can use Habana Gaudi devices in Open Data Hub, you must install the necessary dependencies and deploy the HabanaAI Operator.

Prerequisites

You have logged in to OpenShift Container Platform.
You have the cluster-admin role in OpenShift Container Platform.

Procedure

To enable Habana Gaudi devices in Open Data Hub, follow the instructions at HabanaAI Operator for OpenShift.
From the Open Data Hub dashboard, click Settings → Accelerator profiles.

The Accelerator profiles page appears, displaying existing accelerator profiles. To enable or disable an existing accelerator profile, on the row containing the relevant accelerator profile, click the toggle in the Enable column.
Click Create accelerator profile.

The Create accelerator profile dialog opens.
In the Name field, enter a name for the Habana Gaudi device.
In the Identifier field, enter a unique string that identifies the Habana Gaudi device, for example, habana.ai/gaudi.
Optional: In the Description field, enter a description for the Habana Gaudi device.
To enable or disable the accelerator profile for the Habana Gaudi device immediately after creation, click the toggle in the Enable column.
Optional: Add a toleration to schedule pods with matching taints.
1. Click Add toleration.
  
  The Add toleration dialog opens.
2. From the Operator list, select one of the following options:
  - Equal - The key/value/effect parameters must match. This is the default.
  - Exists - The key/effect parameters must match. You must leave a blank value parameter, which matches any.
3. From the Effect list, select one of the following options:
  - None
  - NoSchedule - New pods that do not match the taint are not scheduled onto that node. Existing pods on the node remain.
  - PreferNoSchedule - New pods that do not match the taint might be scheduled onto that node, but the scheduler tries not to. Existing pods on the node remain.
  - NoExecute - New pods that do not match the taint cannot be scheduled onto that node. Existing pods on the node that do not have a matching toleration are removed.
4. In the Key field, enter the toleration key habana.ai/gaudi. The key is any string, up to 253 characters. The key must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.
5. In the Value field, enter a toleration value. The value is any string, up to 63 characters. The value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores.
6. In the Toleration Seconds section, select one of the following options to specify how long a pod stays bound to a node that has a node condition.
  - Forever - Pods stays permanently bound to a node.
  - Custom value - Enter a value, in seconds, to define how long pods stay bound to a node that has a node condition.
7. Click Add.
Click Create accelerator profile.

Verification

From the Administrator perspective, the following Operators appear on the Operators → Installed Operators page.
- HabanaAI
- Node Feature Discovery (NFD)
- Kernel Module Management (KMM)
The Accelerator list displays the Habana Gaudi accelerator on the Start a notebook server page. After you select an accelerator, the Number of accelerators field appears, which you can use to choose the number of accelerators for your notebook server.
The accelerator profile appears on the Accelerator profiles page
The accelerator profile appears on the Instances tab on the details page for the AcceleratorProfile custom resource definition (CRD).

Additional resources

Troubleshooting common problems in Jupyter for administrators

If your users are experiencing errors in Open Data Hub relating to Jupyter, their notebooks, or their notebook server, read this section to understand what could be causing the problem, and how to resolve the problem.

A user receives a 404: Page not found error when logging in to Jupyter

Problem

If you have configured specialized user groups for Open Data Hub, the user name might not be added to the default user group for Open Data Hub.

Diagnosis

Check whether the user is part of the default user group.

Find the names of groups allowed access to Jupyter.
1. Log in to the OpenShift Container Platform web console.
2. Click User Management → Groups.
3. Click the name of your user group, for example, {oai-user-group}.
  
  The Group details page for that group appears.
Click the Details tab for the group and confirm that the Users section for the relevant group contains the users who have permission to access Jupyter.

Resolution

If the user is not added to any of the groups allowed access to Jupyter, add them.

A user’s notebook server does not start

Problem

The OpenShift Container Platform cluster that hosts the user’s notebook server might not have access to enough resources, or the Jupyter pod may have failed.

Diagnosis

Log in to the OpenShift Container Platform web console.
Delete and restart the notebook server pod for this user.
1. Click Workloads → Pods and set the Project to rhods-notebooks.
2. Search for the notebook server pod that belongs to this user, for example, jupyter-nb-<username>-*.
  
  If the notebook server pod exists, an intermittent failure may have occurred in the notebook server pod.
  
  If the notebook server pod for the user does not exist, continue with diagnosis.
Check the resources currently available in the OpenShift Container Platform cluster against the resources required by the selected notebook server image.

If worker nodes with sufficient CPU and RAM are available for scheduling in the cluster, continue with diagnosis.
Check the state of the Jupyter pod.

Resolution

If there was an intermittent failure of the notebook server pod:
1. Delete the notebook server pod that belongs to the user.
2. Ask the user to start their notebook server again.
If the notebook server does not have sufficient resources to run the selected notebook server image, either add more resources to the OpenShift Container Platform cluster, or choose a smaller image size.

The user receives a database or disk is full error or a no space left on device error when they run notebook cells

Problem

The user might have run out of storage space on their notebook server.

Diagnosis

Log in to Jupyter and start the notebook server that belongs to the user having problems. If the notebook server does not start, follow these steps to check whether the user has run out of storage space:
1. Log in to the OpenShift Container Platform web console.
2. Click Workloads → Pods and set the Project to rhods-notebooks.
3. Click the notebook server pod that belongs to this user, for example, jupyter-nb-<idp>-<username>-*.
4. Click Logs. The user has exceeded their available capacity if you see lines similar to the following:
  Unexpected error while saving file: XXXX database or disk is full

Resolution

Increase the user’s available storage by expanding their persistent volume.
Work with the user to identify files that can be deleted from the /opt/app-root/src directory on their notebook server to free up their existing storage space.

Note	When you delete files using the JupyterLab file explorer, the files move to the hidden `/opt/app-root/src/.local/share/Trash/files` folder in the persistent storage for the notebook. To free up storage space for notebooks, you must permanently delete these files.

Troubleshooting common problems in Jupyter for users

If you are seeing errors in Open Data Hub related to Jupyter, your notebooks, or your notebook server, read this section to understand what could be causing the problem.

I see a 403: Forbidden error when I log in to Jupyter

Problem

If your administrator has configured specialized user groups for Open Data Hub, your user name might not be added to the default user group or the default administrator group for Open Data Hub.

Resolution

Contact your administrator so that they can add you to the correct group/s.

My notebook server does not start

Problem

The OpenShift Container Platform cluster that hosts your notebook server might not have access to enough resources, or the Jupyter pod may have failed.

Resolution

Check the logs in the Events section in OpenShift for error messages associated with the problem. For example:

Server requested
2021-10-28T13:31:29.830991Z [Warning] 0/7 nodes are available: 2 Insufficient memory,
2 node(s) had taint {node-role.kubernetes.io/infra: }, that the pod didn't tolerate, 3 node(s) had taint {node-role.kubernetes.io/master: },
that the pod didn't tolerate.

Contact your administrator with details of any relevant error messages so that they can perform further checks.

I see a database or disk is full error or a no space left on device error when I run my notebook cells

Problem

You might have run out of storage space on your notebook server.

Resolution

Contact your administrator so that they can perform further checks.

QUICK LINKS

STAY IN TOUCH

Working on data science projects

Creating and importing notebooks

Creating a new notebook

Notebook images for data scientists

Uploading an existing notebook file from local storage

Uploading an existing notebook file from a Git repository using JupyterLab

Uploading an existing notebook file from a Git repository using the command line interface

Collaborating on notebooks using Git

Uploading an existing notebook file from a Git repository using JupyterLab

Uploading an existing notebook file from a Git repository using the command line interface

Updating your project with changes from a remote Git repository

Pushing project changes to a Git repository

Working on data science projects

Using data science projects

Creating a data science project

Updating a data science project

Deleting a data science project

Using project workbenches

Creating a project workbench

Starting a workbench

Updating a project workbench

Deleting a workbench from a data science project

Using data connections

Adding a data connection to your data science project

Deleting a data connection

Updating a connected data source

Configuring cluster storage

Adding cluster storage to your data science project

Updating cluster storage

Deleting cluster storage from a data science project

Configuring data science pipelines

Configuring a pipeline server

Defining a pipeline

Importing a data science pipeline

Configuring access to data science projects

Configuring access to data science projects

Sharing access to a data science project

Updating access to a data science project

Removing access to a data science project

Viewing Python packages installed on your notebook server

Installing Python packages on your notebook server

Updating notebook server settings by restarting your server

Working with data science pipelines

Enabling Data Science Pipelines 2.0

Installing Open Data Hub with DSP 2.0

Upgrading to DSP 2.0

Managing data science pipelines

Configuring a pipeline server

Defining a pipeline

Importing a data science pipeline

Downloading a data science pipeline version

Deleting a data science pipeline

Deleting a pipeline server

Viewing the details of a pipeline server

Viewing existing pipelines

Managing pipeline runs

Overview of pipeline runs

Viewing active pipeline runs

Executing a pipeline run

Stopping an active pipeline run

Duplicating an active pipeline run

Viewing scheduled pipeline runs

Scheduling a pipeline run using a cron job

Scheduling a pipeline run

Duplicating a scheduled pipeline run

Deleting a scheduled pipeline run

Viewing the details of a pipeline run

Viewing archived pipeline runs

Archiving a pipeline run

Restoring an archived pipeline run

Deleting an archived pipeline run

Duplicating an archived pipeline run

Working with pipeline logs

About pipeline logs

Viewing pipeline step logs

Downloading pipeline step logs

Working with pipelines in JupyterLab

Overview of pipelines in JupyterLab

Accessing the pipeline editor

Creating a runtime configuration