Merge remote-tracking branch 'upstream/main'

Author: dchourasia

CONTRIBUTING.md

@@ -40,6 +40,13 @@ Pull requests are the best way to propose changes to the notebooks repository:
 - Run the [piplock-renewal.yaml](https://github.com/opendatahub-io/notebooks/blob/main/.github/workflows/piplock-renewal.yaml) against your fork branch, check [here](https://github.com/opendatahub-io/notebooks/blob/main/README.md) for more info.
 - Test the changes locally, by manually running the `$ make jupyter-${NOTEBOOK_NAME}-ubi8-python-3.8` from the terminal.
 
+### Working with linters
+
+- Run pre-commit before you commit, to lint the Python sources that have been put under its management
+    ```
+    uv run pre-commit run --all-files
+    ```
+- If you like, you can install pre-commit to run automatically using `uv run pre-commit install`, as per its [install instructions](https://pre-commit.com/#3-install-the-git-hook-scripts)
 
 ### Some basic instructions how to apply the new tests into [openshift-ci](https://github.com/openshift/release)
 

codeserver/ubi9-python-3.11/Dockerfile.cpu

@@ -17,11 +17,12 @@ USER 1001
 # Install micropipenv to deploy packages from Pipfile.lock
 RUN pip install --no-cache-dir -U "micropipenv[toml]"
 
-# Install the oc client
+# Install the oc client begin
 RUN curl -L https://mirror.openshift.com/pub/openshift-v4/$(uname -m)/clients/ocp/stable/openshift-client-linux.tar.gz \
         -o /tmp/openshift-client-linux.tar.gz && \
     tar -xzvf /tmp/openshift-client-linux.tar.gz oc && \
     rm -f /tmp/openshift-client-linux.tar.gz
+# Install the oc client end
 
 
 ####################

codeserver/ubi9-python-3.12/Dockerfile.cpu

@@ -17,11 +17,12 @@ USER 1001
 # Install micropipenv to deploy packages from Pipfile.lock
 RUN pip install --no-cache-dir -U "micropipenv[toml]"
 
-# Install the oc client
+# Install the oc client begin
 RUN curl -L https://mirror.openshift.com/pub/openshift-v4/$(uname -m)/clients/ocp/stable/openshift-client-linux.tar.gz \
         -o /tmp/openshift-client-linux.tar.gz && \
     tar -xzvf /tmp/openshift-client-linux.tar.gz oc && \
     rm -f /tmp/openshift-client-linux.tar.gz
+# Install the oc client end
 
 
 ####################

docs/developer-guide.md

@@ -1,8 +1,8 @@
 The following sections are aimed to provide a comprehensive guide for developers, enabling them to understand the project's architecture and seamlessly contribute to its development.
 
 ## Getting Started
-This project utilizes three branches for the development: the **main** branch, which hosts the latest development, and t**wo additional branches for each release**.
-These release branches follow a specific naming format: YYYYx, where "YYYY" represents the year, and "x" is an increasing letter. Thus, they help to keep working on minor updates and bug fixes on the supported versions (N & N-1) of each workbench. 
+This project utilizes three branches for the development: the **main** branch, which hosts the latest development, and **two additional branches for each release**.
+These release branches follow a specific naming format: YYYYx, where "YYYY" represents the year, and "x" is an increasing letter. Thus, they help to keep working on minor updates and bug fixes on the supported versions (N & N-1) of each workbench.
 
 ## Architecture
 The structure of the notebook's build chain is derived from the parent image. To better comprehend this concept, refer to the following graph.
@@ -19,30 +19,30 @@ Detailed instructions on how developers can contribute to this project can be fo
 ## Workbench ImageStreams
 
 ODH supports multiple out-of-the-box pre-built workbench images ([provided in this repository](https://github.com/opendatahub-io/notebooks)). For each of those workbench images, there is a dedicated ImageStream object definition. This ImageStream object references the actual image tag(s) and contains additional metadata that describe the workbench image.
-  
+
 ### **Annotations**
 
 Aside from the general ImageStream config values, there are additional annotations that can be provided in the workbench ImageStream definition. This additional data is leveraged further by the [odh-dashboard](https://github.com/opendatahub-io/odh-dashboard/).
 
-### **ImageStream-specific annotations**  
-The following labels and annotations are specific to the particular workbench image. They are provided in their respective sections in the `metadata` section. 
+### **ImageStream-specific annotations**
+The following labels and annotations are specific to the particular workbench image. They are provided in their respective sections in the `metadata` section.
 ```yaml
 metadata:
   labels:
     ...
   annotations:
     ...
 ```
-### **Available labels**  
--  **`opendatahub.io/notebook-image:`** - a flag that determines whether the ImageStream references a workbench image that is meant be shown in the UI
+### **Available labels**
+- **`opendatahub.io/notebook-image:`** - a flag that determines whether the ImageStream references a workbench image that is meant be shown in the UI
 ### **Available annotations**
 - **`opendatahub.io/notebook-image-url:`** - a URL reference to the source of the particular workbench image
 - **`opendatahub.io/notebook-image-name:`** - a desired display name string for the particular workbench image (used in the UI)
-- **`opendatahub.io/notebook-image-desc:`** - a desired description string of the of the particular workbench image (used in the UI) 
+- **`opendatahub.io/notebook-image-desc:`** - a desired description string of the particular workbench image (used in the UI)
 - **`opendatahub.io/notebook-image-order:`** - an index value for the particular workbench ImageStream (used by the UI to list available workbench images in a specific order)
 - **`opendatahub.io/recommended-accelerators`** - a string that represents the list of recommended hardware accelerators for the particular workbench ImageStream (used in the UI)
 
-### **Tag-specific annotations**  
+### **Tag-specific annotations**
 One ImageStream can reference multiple image tags. The following annotations are specific to a particular workbench image tag and are provided in its `annotations:` section.
 ```yaml
 spec:
@@ -54,17 +54,19 @@ spec:
         name: image-repository/tag
       name: tag-name
 ```
-### **Available annotations**  
-  - **`opendatahub.io/notebook-software:`** - a string that represents the technology stack included within the workbench image. Each technology in the list is described by its name and the version used (e.g. `'[{"name":"CUDA","version":"11.8"},{"name":"Python","version":"v3.9"}]`')
-  - **`opendatahub.io/notebook-python-dependencies:`** -  a string that represents the list of Python libraries included within the workbench image. Each library is described by its name and currently used version (e.g. `'[{"name":"Numpy","version":"1.24"},{"name":"Pandas","version":"1.5"}]'`)
-  - **`openshift.io/imported-from:`** - a reference to the image repository where the workbench image was obtained (e.g. `quay.io/repository/opendatahub/workbench-images`)
-  - **`opendatahub.io/workbench-image-recommended:`** - a flag that allows the ImageStream tag to be marked as Recommended (used by the UI to distinguish which tags are recommended for use, e.g., when the workbench image offers multiple tags to choose from)
+### **Available per-tag annotations**
+- **`opendatahub.io/notebook-software:`** - a string that represents the technology stack included within the workbench image. Each technology in the list is described by its name and the version used (e.g. `'[{"name":"CUDA","version":"11.8"},{"name":"Python","version":"v3.9"}]`')
+- **`opendatahub.io/notebook-python-dependencies:`** - a string that represents the list of Python libraries included within the workbench image. Each library is described by its name and currently used version (e.g. `'[{"name":"Numpy","version":"1.24"},{"name":"Pandas","version":"1.5"}]'`)
+- **`openshift.io/imported-from:`** - a reference to the image repository where the workbench image was obtained (e.g. `quay.io/repository/opendatahub/workbench-images`)
+- **`opendatahub.io/workbench-image-recommended:`** - a flag that allows the ImageStream tag to be marked as Recommended (used by the UI to distinguish which tags are recommended for use, e.g., when the workbench image offers multiple tags to choose from)
+- **`opendatahub.io/image-tag-outdated:`** - a flag that determines whether the image stream will be hidden from the list of available image versions in the workbench spawner dialog. Workbenches previously started with this image will continue to function.
+- **`opendatahub.io/notebook-build-commit:`** - the commit hash of the notebook image build that was used to create the image. This is shown in Dashboard webui starting with RHOAI 2.22.
 
-### **ImageStream definitions for the supported out-of-the-box images in ODH**  
+### **ImageStream definitions for the supported out-of-the-box images in ODH**
 
 The ImageStream definitions of the out-of-the-box workbench images for ODH can be found [here](https://github.com/opendatahub-io/notebooks/tree/main/manifests).
 
-### **Example ImageStream object definition**  
+### **Example ImageStream object definition**
 
 An exemplary, non-functioning ImageStream object definition that uses all the aforementioned annotations is provided below.
 
@@ -128,7 +130,7 @@ The Openshift CI is also configured to run the unit and integration tests:
 
 ```
 tests:
-  - as: notebooks-e2e-tests 
+  - as: notebooks-e2e-tests
     steps:
       test:
         - as: ${NOTEBOOK_IMAGE_NAME}-e2e-tests
@@ -149,7 +151,7 @@ This GitHub action is configured to be triggered on a weekly basis, specifically
 This GitHub action is configured to be triggered on a daily basis and synchronizes the selected projects from their upstream repositories to their downstream counterparts.
 
 ### **Digest Updater workflow on the manifests** [[Link]](https://github.com/opendatahub-io/odh-manifests/blob/master/.github/workflows/notebooks-digest-updater-upstream.yaml)
- 
+
 This GitHub action is designed to be triggered on a weekly basis, specifically every Friday at 12:00 AM UTC. Its primary purpose is to automate the process of updating the SHA digest of the notebooks. It achieves this by fetching the new SHA values from the quay.io registry and updating the [param.env](https://github.com/opendatahub-io/odh-manifests/blob/master/notebook-images/base/params.env) file, which is hosted on the odh-manifest repository. By automatically updating the SHA digest, this action ensures that the notebooks remain synchronized with the latest changes.
 
 ### **Digest Updater workflow on the live-builder** [[Link]](https://gitlab.cee.redhat.com/data-hub/rhods-live-builder/-/blob/main/.gitlab/notebook-sha-digest-updater.yml)
@@ -159,6 +161,6 @@ This GitHub action works with the same logic as the above and is designed to be
 
 ### **Quay security scan** [[Link]](https://github.com/opendatahub-io/notebooks/blob/main/.github/workflows/sec-scan.yml)
 
-This GitHub action is designed to be triggered on a weekly basis. It generates a summary of security vulnerabilities reported by [Quay](https://quay.io/) for the latest images built for different versions of notebooks. 
-  
+This GitHub action is designed to be triggered on a weekly basis. It generates a summary of security vulnerabilities reported by [Quay](https://quay.io/) for the latest images built for different versions of notebooks.
+
 [Previous Page](https://github.com/opendatahub-io/notebooks/wiki/Workbenches) | [Next Page](https://github.com/opendatahub-io/notebooks/wiki/User-Guide)

examples/README.md

@@ -0,0 +1,83 @@
+# Examples
+
+## JupyterLab with Elyra
+
+This Workbench image installs JupyterLab and the ODH-Elyra extension.
+
+The main difference between the [upstream Elyra](https://github.com/elyra-ai/elyra) and the [ODH-Elyra fork](https://github.com/opendatahub-io/elyra) is that the fork implements Argo Pipelines support, which is required for executing pipelines in OpenDataHub/OpenShift AI.
+Specifically, the fork already includes the changes from [elyra-ai/elyra #3273](https://github.com/elyra-ai/elyra/pull/3273), which is still pending upstream.
+
+### Design
+
+The workbench is based on a Source-to-Image (S2I) UBI9 Python 3.11 image.
+This means—besides having Python 3.11 installed—that it also has the following
+* Python virtual environment at `/opt/app-root` is activated by default
+* `HOME` directory is set to `/opt/app-root/src`
+* port 8888 is `EXPOSE`D by default
+
+These characteristics are required for OpenDataHub workbenches to function.
+
+#### Integration with OpenDataHub Notebook Controller and Notebook Dashboard
+
+#### OpenDataHub Dashboard
+
+Dashboard automatically populates an environment variable named `NOTEBOOK_ARGS` when starting a container from this image.
+This variable contains configurations that are necessary to integrate with Dashboard regarding launching the Workbench and logging off.
+
+Reference: https://github.com/opendatahub-io/odh-dashboard/blob/95d80a0cccd5053dc0ca372effcdcd8183a0d5b8/frontend/src/api/k8s/notebooks.ts#L143-L149
+
+Furthermore, when configuring a workbench, the default Persistent Volume Claim (PVC) is created and volume is mounted at `/opt/app-root/src` in the workbench container.
+This means that changing the user's `HOME` directory from the expected default is inadvisable.
+It further means that whatever the original content of `/opt/app-root/src` in the image may be, it will be shadowed by the PVC.
+
+##### OpenDataHub Notebook Controller
+
+During the Notebook Custom Resource (CR) creation, the mutating webhook in Notebook Controller is triggered.
+This webhook is responsible for configuring OAuth Proxy, certificate bundles, pipeline runtime, runtime images, and maybe more.
+It also creates a service and OpenShift route to make the Workbench reachable from the outside of the cluster.
+
+**OAuth Proxy** is configured to connect to port 8888 of the workbench container (discussed above) and listen for incoming connections on port 8443.
+
+Reference: https://github.com/opendatahub-io/kubeflow/blob/eacf63cdaed4db766a6503aa413e388e1d2721ef/components/odh-notebook-controller/controllers/notebook_webhook.go#L114-L121
+
+**Certificate bundles** are added as a file-mounted configmap at `/etc/pki/tls/custom-certs/ca-bundle.crt`.
+This is a nonstandard location, so it is necessary to also add environment variables that instruct various software to reference this bundle during operation.
+
+Reference:
+* https://github.com/opendatahub-io/kubeflow/blob/eacf63cdaed4db766a6503aa413e388e1d2721ef/components/odh-notebook-controller/controllers/notebook_webhook.go#L598
+* https://github.com/opendatahub-io/kubeflow/blob/eacf63cdaed4db766a6503aa413e388e1d2721ef/components/odh-notebook-controller/controllers/notebook_webhook.go#L601-L607
+
+**Pipeline runtime configuration** is obtained from a Data Science Pipeline Application (DSPA) CR.
+The DSPA CR is first located in the same project where the workbench is being started, a secret with the connection data is created, and then this secret is mounted.
+The secret is mounted under `/opt/app-root/runtimes/`.
+
+Reference: https://github.com/opendatahub-io/kubeflow/blob/eacf63cdaed4db766a6503aa413e388e1d2721ef/components/odh-notebook-controller/controllers/notebook_dspa_secret.go#L42C28-L42C50
+
+IMPORTANT: the `setup-elyra.sh` script in this repo relies on this location.
+
+**Runtime images** are processed very similarly to the DSPA configuration.
+First, image stream resources are examined, and then a configmap is created and mounted to every newly started workbench.
+The mount location is under `/opt/app-root/pipeline-runtimes/`.
+
+Reference: https://github.com/opendatahub-io/kubeflow/blob/eacf63cdaed4db766a6503aa413e388e1d2721ef/components/odh-notebook-controller/controllers/notebook_runtime.go#L25C19-L25C51
+
+IMPORTANT: the `setup-elyra.sh` script in this repo again relies on this location.
+
+### Build
+
+```shell
+podman build -f examples/jupyterlab-with-elyra/Dockerfile -t quay.io/your-username/jupyterlab-with-elyra:latest .
+podman push quay.io/your-username/jupyterlab-with-elyra:latest
+```
+
+### Deploy
+
+Open the `Settings > Workbench images` page in OpenDataHub Dashboard.
+Click on the `Import new image` button and add the image you have just pushed.
+The `Image location` field should be set to `quay.io/your-username/jupyterlab-with-elyra:latest`, or wherever the image is pushed and available for the cluster to pull.
+Values of other fields do not matter for functionality, but they let you keep better track of previously imported images.
+
+There is a special ODH Dashboard feature that alerts you when you are using a workbench image that lists the `elyra` instead of `odh-elyra` package.
+This code will have to be updated when `elyra` also gains support for Argo Pipelines, but for now it does the job.
+
+Reference: https://github.com/opendatahub-io/odh-dashboard/blob/2ced77737a1b1fc24b94acac41245da8b29468a4/frontend/src/concepts/pipelines/elyra/utils.ts#L152-L162

examples/jupyterlab-with-elyra/Dockerfile

@@ -0,0 +1,89 @@
+########
+# base #
+########
+
+# https://catalog.redhat.com/software/containers/registry/registry.access.redhat.com/repository/ubi9/python-311
+FROM registry.access.redhat.com/ubi9/python-311:latest
+# Subsequent code may leverages the folloving definitions from the base image:
+# ENV APP_ROOT=/opt/app-root
+# ENV HOME="${APP_ROOT}/src"
+# ENV PYTHON_VERSION=3.11
+# ENV PYTHONUNBUFFERED=1
+# ENV PYTHONIOENCODING=UTF-8
+# ENV PIP_NO_CACHE_DIR=off
+# ENV BASH_ENV="${APP_ROOT}/bin/activate"
+# ENV ENV="${APP_ROOT}/bin/activate"
+
+# OS packages needs to be installed as root
+USER root
+
+# Install useful OS packages
+RUN dnf install -y mesa-libGL skopeo && dnf clean all && rm -rf /var/cache/yum
+
+# Other apps and tools shall be installed as default user
+# - Kuberneres requires using numeric IDs for the final USER command
+# - Openshift's SCC restricted-v2 policy runs images under random UID and GID of 0
+USER 1001:0
+WORKDIR /opt/app-root
+
+ARG JUPYTER_REUSABLE_UTILS=jupyter/utils
+ARG MINIMAL_SOURCE_CODE=jupyter/minimal/ubi9-python-3.11
+ARG DATASCIENCE_SOURCE_CODE=jupyter/datascience/ubi9-python-3.11
+
+# Emplace and activate our entrypoint script
+COPY ${MINIMAL_SOURCE_CODE}/start-notebook.sh /opt/app-root/bin/
+ENTRYPOINT ["/opt/app-root/bin/start-notebook.sh"]
+# Copy JupyterLab config from utils directory
+COPY ${JUPYTER_REUSABLE_UTILS} /opt/app-root/bin/utils/
+# Copy Elyra setup script and various utils where start-notebook.sh expects it
+COPY ${DATASCIENCE_SOURCE_CODE}/setup-elyra.sh ${DATASCIENCE_SOURCE_CODE}/utils /opt/app-root/bin/utils/
+
+# Install Python packages and Jupyterlab extensions
+# https://www.docker.com/blog/introduction-to-heredocs-in-dockerfiles/
+
+COPY <<EOF requirements.txt
+--index-url https://pypi.org/simple
+
+# JupyterLab
+jupyterlab==4.2.7
+jupyter-bokeh~=4.0.5
+jupyter-server~=2.15.0
+jupyter-server-proxy~=4.4.0
+jupyter-server-terminals~=0.5.3
+jupyterlab-git~=0.50.1
+jupyterlab-lsp~=5.1.0
+jupyterlab-widgets~=3.0.13
+jupyter-resource-usage~=1.1.1
+nbdime~=4.0.2
+nbgitpuller~=1.2.2
+
+# Elyra
+odh-elyra==4.2.1
+kfp~=2.12.1
+
+# Miscellaneous datascience packages
+matplotlib~=3.10.1
+numpy~=2.2.3
+# ...
+EOF
+
+RUN echo "Installing software and packages" && \
+    pip install -r requirements.txt && \
+    rm -f ./Pipfile.lock && \
+    # Prepare directories for elyra runtime configuration
+    mkdir /opt/app-root/runtimes && \
+    mkdir /opt/app-root/pipeline-runtimes && \
+    # Remove default Elyra runtime-images
+    rm /opt/app-root/share/jupyter/metadata/runtime-images/*.json && \
+    # Replace Notebook's launcher, "(ipykernel)" with Python's version 3.x.y
+    sed -i -e "s/Python.*/$(python --version | cut -d '.' -f-2)\",/" /opt/app-root/share/jupyter/kernels/python3/kernel.json && \
+    # Copy jupyter configuration
+    cp /opt/app-root/bin/utils/jupyter_server_config.py /opt/app-root/etc/jupyter && \
+    # Disable announcement plugin of jupyterlab
+    jupyter labextension disable "@jupyterlab/apputils-extension:announcements" && \
+    # Fix permissions to support pip in Openshift environments
+    chmod -R g+w /opt/app-root/lib/python3.11/site-packages && \
+    fix-permissions /opt/app-root -P
+
+# Switch dir to $HOME
+WORKDIR /opt/app-root/src