Open Data Hub logo
DOCS
BLOG
COMMUNITY
GITHUB
GET STARTED

Info alert:Important Notice

Please note that more information about the previous v2 releases can be found here. You can use "Find a release" search bar to search for a particular release.

Managing resources

As an Open Data Hub administrator, you can manage the following resources:

  • Open Data Hub admin and user groups

  • Custom workbench images

  • Cluster PVC size

  • Cluster storage classes

  • Jupyter notebook servers

Selecting Open Data Hub administrator and user groups

By default, all users authenticated in OpenShift can access Open Data Hub.

Also by default, users with cluster-admin permissions are Open Data Hub administrators. A cluster admin is a superuser that can perform any action in any project in the OpenShift cluster. When bound to a user with a local binding, they have full control over quota and every action on every resource in the project.

After a cluster admin user defines additional administrator and user groups in OpenShift, you can add those groups to Open Data Hub by selecting them in the Open Data Hub dashboard.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

  • The groups that you want to select as administrator and user groups for Open Data Hub already exist in OpenShift Container Platform. For more information, see Managing users and groups.

Procedure

  1. From the Open Data Hub dashboard, click Settings → User management.

  2. Select your Open Data Hub administrator groups: Under Data science administrator groups, click the text box and select an OpenShift group. Repeat this process to define multiple administrator groups.

  3. Select your Open Data Hub user groups: Under Data science user groups, click the text box and select an OpenShift group. Repeat this process to define multiple user groups.

    Important
    		 The system:authenticated setting allows all users authenticated in OpenShift to access Open Data Hub.

  4. Click Save changes.

Verification

  • Administrator users can successfully log in to Open Data Hub and have access to the Settings navigation menu.

  • Non-administrator users can successfully log in to Open Data Hub. They can also access and use individual components, such as projects and workbenches.

Importing a custom workbench image

You can import custom workbench images that cater to your Open Data Hub project’s specific requirements. From the Notebook images page, you can enable or disable a previously imported workbench image and create an accelerator profile as a recommended accelerator for existing notebook images.

You must import it so that your Open Data Hub users (data scientists) can access it when they create a project workbench.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

  • Your custom image exists in an image registry that is accessible to Open Data Hub.

  • The Settings → Notebook images dashboard navigation menu option is enabled, as described in Creating a custom image from a default Open Data Hub image.

  • If you want to associate an accelerator with the custom image that you want to import, you know the accelerator’s identifier - the unique string that identifies the hardware accelerator.

Procedure

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

    The Notebook images page appears. Previously imported images are displayed. To enable or disable a previously imported image, on the row containing the relevant image, click the toggle in the Enable column.

  2. Optional: If you want to associate an accelerator and you have not already created an accelerator profile, click Create profile on the row containing the image and complete the relevant fields. If the image does not contain an accelerator identifier, you must manually configure one before creating an associated accelerator profile.

  3. Click Import new image. Alternatively, if no previously imported images were found, click Import image.

    The Import Notebook images dialog appears.

  4. In the Image location field, enter the URL of the repository containing the image. For example: quay.io/my-repo/my-image:tag, quay.io/my-repo/my-image@sha256:xxxxxxxxxxxxx, or docker.io/my-repo/my-image:tag.

  5. In the Name field, enter an appropriate name for the image.

  6. Optional: In the Description field, enter a description for the image.

  7. Optional: From the Accelerator identifier list, select an identifier to set its accelerator as recommended with the image. If the image contains only one accelerator identifier, the identifier name displays by default.

  8. Optional: Add software to the image. After the import has completed, the software is added to the image’s meta-data and displayed on the Jupyter server creation page.

    1. Click the Software tab.

    2. Click the Add software button.

    3. Click Edit (The Edit icon).

    4. Enter the Software name.

    5. Enter the software Version.

    6. Click Confirm (The Confirm icon) to confirm your entry.

    7. To add additional software, click Add software, complete the relevant fields, and confirm your entry.

  9. Optional: Add packages to the notebook images. After the import has completed, the packages are added to the image’s meta-data and displayed on the Jupyter server creation page.

    1. Click the Packages tab.

    2. Click the Add package button.

    3. Click Edit (The Edit icon).

    4. Enter the Package name. For example, if you want to include data science pipeline V2 automatically, as a runtime configuration, type odh-elyra.

    5. Enter the package Version. For example, type 3.16.7.

    6. Click Confirm (The Confirm icon) to confirm your entry.

    7. To add an additional package, click Add package, complete the relevant fields, and confirm your entry.

  10. Click Import.

Verification

  • The image that you imported is displayed in the table on the Notebook images page.

  • Your custom image is available for selection when a user creates a workbench.

Additional resources

Managing cluster PVC size

Configuring the default PVC size for your cluster

To configure how resources are claimed within your Open Data Hub cluster, you can change the default size of the cluster’s persistent volume claim (PVC) ensuring that the storage requested matches your common storage workflow. PVCs are requests for resources in your cluster and also act as claim checks to the resource.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

Note
 Changing the PVC setting restarts the Jupyter pod and makes Jupyter unavailable for up to 30 seconds. As a workaround, it is recommended that you perform this action outside of your organization’s typical working day.
Procedure

  1. From the Open Data Hub dashboard, click Settings → Cluster settings.

  2. Under PVC size, enter a new size in gibibytes or mebibytes.

  3. Click Save changes.

Verification

  • New PVCs are created with the default storage size that you configured.

Additional resources

Restoring the default PVC size for your cluster

To change the size of resources utilized within your Open Data Hub cluster, you can restore the default size of your cluster’s persistent volume claim (PVC).

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

Procedure

  1. From the Open Data Hub dashboard, click Settings → Cluster settings.

  2. Click Restore Default to restore the default PVC size of 20GiB.

  3. Click Save changes.

Verification

  • New PVCs are created with the default storage size of 20 GiB.

Additional resources

Managing storage classes

OpenShift Container Platform cluster administrators use storage classes to describe the different types of storage that is available in their cluster. These storage types can represent different quality-of-service levels, backup policies, or other custom policies set by cluster administrators.

Configuring storage class settings

As an Open Data Hub administrator, you can manage OpenShift Container Platform cluster storage class settings for usage within Open Data Hub, including the display name, description, and whether users can use the storage class when creating or editing cluster storage. These settings do not impact the storage class within OpenShift Container Platform.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

Procedure

  1. From the Open Data Hub dashboard, click Settings → Storage classes.

    The Storage classes page appears, displaying the storage classes for your cluster as defined in OpenShift Container Platform.

  2. To enable or disable a storage class for users, on the row containing the storage class, click the toggle in the Enable column.

  3. To edit a storage class, on the row containing the storage class, click the action menu (⋮) and then select Edit.

    The Edit storage class details dialog opens.

  4. Optional: In the Display Name field, update the name for the storage class. This name is used only in Open Data Hub and does not impact the storage class within OpenShift Container Platform.

  5. Optional: In the Description field, update the description for the storage class. This description is used only in Open Data Hub and does not impact the storage class within OpenShift Container Platform.

  6. Click Save.

Verification

  • If you enabled a storage class, the storage class is available for selection when a user adds cluster storage to a data science project or workbench.

  • If you disabled a storage class, the storage class is not available for selection when a user adds cluster storage to a data science project or workbench.

  • If you edited a storage class name, the updated storage class name is displayed when a user adds cluster storage to a data science project or workbench.

Additional resources

Configuring the default storage class for your cluster

As an Open Data Hub administrator, you can configure the default storage class for Open Data Hub to be different from the default storage class in OpenShift Container Platform.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

Procedure

  1. From the Open Data Hub dashboard, click Settings → Storage classes.

    The Storage classes page appears, displaying the storage classes for your cluster as defined in OpenShift Container Platform.

  2. If the storage class that you want to set as the default is not enabled, on the row containing the storage class, click the toggle in the Enable column.

  3. To set a storage class as the default for Open Data Hub, on the row containing the storage class, select Set as default.

Verification

  • When a user adds cluster storage to a data science project or workbench, the default storage class that you configured is automatically selected.

Additional resources

Overview of object storage endpoints

To ensure correct configuration of object storage in Open Data Hub, you must format endpoints correctly for the different types of object storage supported. These instructions are for formatting endpoints for Amazon S3, MinIO, or other S3-compatible storage solutions, minimizing configuration errors and ensuring compatibility.

Important

Properly formatted endpoints enable connectivity and reduce the risk of misconfigurations. Use the appropriate endpoint format for your object storage type. Improper formatting might cause connection errors or restrict access to storage resources.

MinIO (On-Cluster)

For on-cluster MinIO instances, use a local endpoint URL format. Ensure the following when configuring MinIO endpoints:

  • Prefix the endpoint with http:// or https:// depending on your MinIO security setup.

  • Include the cluster IP or hostname, followed by the port number if specified.

  • Use a port number if your MinIO instance requires one (default is typically 9000).

Example:

http://minio-cluster.local:9000

Note

Verify that the MinIO instance is accessible within the cluster by checking your cluster DNS settings and network configurations.

Amazon S3

When configuring endpoints for Amazon S3, use region-specific URLs. Amazon S3 endpoints generally follow this format:

  • Prefix the endpoint with https://.

  • Format as <bucket-name>.s3.<region>.amazonaws.com, where <bucket-name> is the name of your S3 bucket, and <region> is the AWS region code (for example, us-west-1, eu-central-1).

Example:

https://my-bucket.s3.us-west-2.amazonaws.com

Note

For improved security and compliance, ensure that your Amazon S3 bucket is in the correct region.

Other S3-Compatible Object Stores

For S3-compatible storage solutions other than Amazon S3, follow the specific endpoint format required by your provider. Generally, these endpoints include the following items:

  • The provider base URL, prefixed with https://.

  • The bucket name and region parameters as specified by the provider.

  • Review the documentation from your S3-compatible provider to confirm required endpoint formats.

  • Replace placeholder values like <bucket-name> and <region> with your specific configuration details.

Warning

Incorrectly formatted endpoints for S3-compatible providers might lead to access denial. Always verify the format in your storage provider documentation to ensure compatibility.

Verification and Troubleshooting

After configuring endpoints, verify connectivity by performing a test upload or accessing the object storage directly through the Open Data Hub dashboard. For troubleshooting, check the following items:

  • Network Accessibility: Confirm that the endpoint is reachable from your Open Data Hub cluster.

  • Authentication: Ensure correct access credentials for each storage type.

  • Endpoint Accuracy: Double-check the endpoint URL format for any typos or missing components.

Additional resources

Managing Jupyter notebook servers

Accessing the Jupyter administration interface

You can use the Jupyter administration interface to control notebook servers in your Open Data Hub environment.

Prerequisite

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

Procedure

  • To access the Jupyter administration interface from Open Data Hub, perform the following actions:

    1. In Open Data Hub, in the Applications section of the left menu, click Enabled.

    2. Locate the Jupyter tile and click Launch application.

    3. On the page that opens when you launch Jupyter, click the Administration tab.

      The Administration page opens.

  • To access the Jupyter administration interface from JupyterLab, perform the following actions:

    1. Click File → Hub Control Panel.

    2. On the page that opens in Open Data Hub, click the Administration tab.

      The Administration page opens.

Verification

  • You can see the Jupyter administration interface.

Starting notebook servers owned by other users

Open Data Hub administrators can start a notebook server for another existing user from the Jupyter administration interface.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

  • You have launched the Jupyter application, as described in Starting a Jupyter notebook server.

Procedure

  1. On the page that opens when you launch Jupyter, click the Administration tab.

  2. On the Administration tab, perform the following actions:

    1. In the Users section, locate the user whose notebook server you want to start.

    2. Click Start server beside the relevant user.

    3. Complete the Start a notebook server page.

    4. Optional: Select the Start server in current tab checkbox if necessary.

    5. Click Start server.

      After the server starts, you see one of the following behaviors:

      • If you previously selected the Start server in current tab checkbox, the JupyterLab interface opens in the current tab of your web browser.

      • If you did not previously select the Start server in current tab checkbox, the Starting server dialog box prompts you to open the server in a new browser tab or in the current tab.

        The JupyterLab interface opens according to your selection.

Verification

  • The JupyterLab interface opens.

Accessing notebook servers owned by other users

Open Data Hub administrators can access notebook servers that are owned by other users to correct configuration errors or to help them troubleshoot problems with their environment.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

  • You have launched the Jupyter application, as described in Starting a Jupyter notebook server.

  • The notebook server that you want to access is running.

Procedure

  1. On the page that opens when you launch Jupyter, click the Administration tab.

  2. On the Administration page, perform the following actions:

    1. In the Users section, locate the user that the notebook server belongs to.

    2. Click View server beside the relevant user.

    3. On the Notebook server control panel page, click Access notebook server.

Verification

  • The user’s notebook server opens in JupyterLab.

Stopping notebook servers owned by other users

Open Data Hub administrators can stop notebook servers that are owned by other users to reduce resource consumption on the cluster, or as part of removing a user and their resources from the cluster.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

  • You have launched the Jupyter application, as described in Starting a Jupyter notebook server.

  • The notebook server that you want to stop is running.

Procedure

  1. On the page that opens when you launch Jupyter, click the Administration tab.

  2. Stop one or more servers.

    • If you want to stop one or more specific servers, perform the following actions:

      1. In the Users section, locate the user that the notebook server belongs to.

      2. To stop the notebook server, perform one of the following actions:

        • Click the action menu (⋮) beside the relevant user and select Stop server.

        • Click View server beside the relevant user and then click Stop notebook server.

          The Stop server dialog box appears.

      3. Click Stop server.

    • If you want to stop all servers, perform the following actions:

      1. Click the Stop all servers button.

      2. Click OK to confirm stopping all servers.

Verification

  • The Stop server link beside each server changes to a Start server link when the notebook server has stopped.

Stopping idle notebooks

You can reduce resource usage in your Open Data Hub deployment by stopping notebook servers that have been idle (without logged in users) for a period of time. This is useful when resource demand in the cluster is high. By default, idle notebooks are not stopped after a specific time limit.

Note

If you have configured your cluster settings to disconnect all users from a cluster after a specified time limit, then this setting takes precedence over the idle notebook time limit. Users are logged out of the cluster when their session duration reaches the cluster-wide time limit.
Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

Procedure

  1. From the Open Data Hub dashboard, click Settings → Cluster settings.

  2. Under Stop idle notebooks, select Stop idle notebooks after.

  3. Enter a time limit, in hours and minutes, for when idle notebooks are stopped.

  4. Click Save changes.

Verification

  • The notebook-controller-culler-config ConfigMap, located in the redhat-ods-applications project on the Workloads → ConfigMaps page, contains the following culling configuration settings:

    • ENABLE_CULLING: Specifies if the culling feature is enabled or disabled (this is false by default).

    • IDLENESS_CHECK_PERIOD: The polling frequency to check for a notebook’s last known activity (in minutes).

    • CULL_IDLE_TIME: The maximum allotted time to scale an inactive notebook to zero (in minutes).

  • Idle notebooks stop at the time limit that you set.

Adding notebook pod tolerations

If you want to dedicate certain machine pools to only running notebook pods, you can allow notebook pods to be scheduled on specific nodes by adding a toleration. Taints and tolerations allow a node to control which pods should (or should not) be scheduled on them. For more information, see Understanding taints and tolerations.

This capability is useful if you want to make sure that notebook servers are placed on nodes that can handle their needs. By preventing other workloads from running on these specific nodes, you can ensure that the necessary resources are available to users who need to work with large notebook sizes.

Prerequisites

  • You have logged in to Open Data Hub as a user with Open Data Hub administrator privileges.

  • You are familiar with OpenShift Container Platform taints and tolerations, as described in Understanding taints and tolerations.

Procedure

  1. From the Open Data Hub dashboard, click Settings → Cluster settings.

  2. Under Notebook pod tolerations, select Add a toleration to notebook pods to allow them to be scheduled to tainted nodes.

  3. In the Toleration key for notebook pods field, enter a toleration key. The key is any string, up to 253 characters. The key must begin with a letter or number, and can contain letters, numbers, hyphens, dots, and underscores. For example, notebooks-only.

  4. Click Save changes. The toleration key is applied to new notebook pods when they are created.

    For existing notebook pods, the toleration key is applied when the notebook pods are restarted. If you are using Jupyter, see Updating notebook server settings by restarting your server. If you are using a workbench in a data science project, see Starting a workbench.

Next step

In OpenShift Container Platform, add a matching taint key (with any value) to the machine pools that you want to dedicate to notebooks. For more information, see Controlling pod placement using node taints.

Verification

  1. In the OpenShift Container Platform console, for a pod that is running, click Workloads → Pods. Otherwise, for a pod that is stopped, click Workloads → StatefulSet.

  2. Search for your workbench pod name and then click the name to open the pod details page.

  3. Confirm that the assigned Node and Tolerations are correct.

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 Open Data Hub user groups, 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.

  1. 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.

  2. 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

  1. Log in to the OpenShift Container Platform web console.

  2. 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.

  3. 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.

  4. 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

  1. 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.