Creating a workbench

Procedure

1. In a terminal window, if you are not already logged in to your OpenShift cluster as a cluster administrator, log in as shown in the following example:

   oc login <openshift_cluster_url> -u <admin_username> -p <password>

2. Define the ImageStream CRD.

   1. Create a YAML manifest file named notebook-image-stream.yaml.

   2. Copy the following configuration and paste it in the notebook-image-stream.yaml file:

      Example ImageStream

      kind: ImageStream
      apiVersion: image.openshift.io/v1
      metadata:
        annotations:
          opendatahub.io/notebook-image-desc: A custom Jupyter Notebook image 

      1

      
          opendatahub.io/notebook-image-name: My Custom Notebook 

      2

      
        name: my-custom-notebook
        namespace: redhat-ods-applications 

      3

      
        labels: 

      4

      
          app.kubernetes.io/created-by: byon
          opendatahub.io/dashboard: 'true'
          opendatahub.io/notebook-image: 'true'
          opendatahub.io/component: 'true'
          platform.opendatahub.io/part-of: 'workbenches'
          app.kubernetes.io/part-of: 'workbenches'
      spec:
        lookupPolicy:
          local: true
        tags:
          - name: '1.0' 

      5

      
            annotations: 

      6

      
              opendatahub.io/notebook-python-dependencies: '[{"name":"PyTorch","version":"2.2"}]' 

      7

      
              opendatahub.io/notebook-software: '[{"name":"Python","version":"v3.11"}]' 

      8

      
              opendatahub.io/workbench-image-recommended: 'true' 

      9

      
              opendatahub.io/image-tag-outdated: 'true' 

      10

      
              opendatahub.io/notebook-build-commit: '3e71410' 

      11

      
            from:
              kind: DockerImage
              name: 'quay.io/modh/rocm-notebooks@sha256:199367d2946..b411433ffbb5f0988279b10150020af22db' 

      12

      
            importPolicy:
            importPolicy:
              importMode: Legacy
            referencePolicy:
              type: Source

      The example YAML file includes the following information:

      1

      A description of the image.

      2

      The image name that is displayed in the drop down menu when a user creates a workbench in the OpenShift AI dashboard.

      3

      The redhat-ods-applications namespace is the default namespace in which the ImageStream CR is created.

      4

      The labels that are required if you want the image to appear in the OpenShift AI dashboard. The app.kubernetes.io/created-by: byon label identifies the origination of the image object.

      5

      Annotations that are required if you want to make the image available in the OpenShift AI dashboard.

      6

      The version for the image. You can configure multiple versions for the same image. For this example, the version is 1.0.

      7

      An annotation that gives the user information about the Python packages and versions that are pre-installed in the image.

      8

      An annotation that specifies information such as the Python version, Jupyter version, or CUDA version.

      9

      An annotation that specifies whether the ImageStream version is the default version of the image. Set this field to 'true' if the ImageStream version is the default. Otherwise, set it to 'false'. You must specify the opendatahub.io/workbench-image-recommended annotation field if there are multiple versions of the image with different configurations. If you have only one version of the image, set the field to 'true'.

      10

      An annotation that specifies whether the image version has tags that are outdated and out of the regular maintenance cycle.

      11

      An annotation that references the commit hash’s build commit ID to identify the sources that the specific tag was built from.

      12

      The image registry path where the image has been uploaded.

3. To create the ImageStream CR, run the following command, where the ImageStream CRD YAML manifest file name is notebook-image-stream.yaml:

   oc create -f notebook-image-stream.yaml

Verification

1. To verify that the ImageStream was successfully created, run the following command, where the name of the ImageStream is my-custom-notebook:

   oc describe imagestream my-custom-notebook -n redhat-ods-applications

   You should see output similar to the following example:

   Example output

   Name:                   my-custom-notebook
   Namespace:              redhat-ods-applications
   Created:                6 minutes ago
   Labels:                 app.kubernetes.io/created-by=byon
                           opendatahub.io/dashboard=true
                           opendatahub.io/notebook-image=true
   Annotations:            kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"image.openshift.io/v1","kind":"ImageStream","metadata":{"annotations":{"opendatahub.io/notebook-image-desc":"A custom Jupyter Notebook image","opendatahub.io/notebook-image-name":"My Custom Notebook"},"labels":{"app.kubernetes.io/created-by":"byon","opendatahub.io/dashboard":"true","opendatahub.io/notebook-image":"true"},"name":"my-custom-notebook","namespace":"redhat-ods-applications"},"spec":{"lookupPolicy":{"local":true},"tags":[{"annotations":{"opendatahub.io/notebook-python-dependencies":"[{\"name\":\"PyTorch\",\"version\":\"2.2\"}]","opendatahub.io/notebook-software":"[{\"name\":\"Python\",\"version\":\"v3.11\"}]","opendatahub.io/workbench-image-recommended":"true"},"from":{"kind":"DockerImage","name":"quay.io/modh/rocm-notebooks@sha256:199367d2946fc8....8279b10150020af22db"},"importPolicy":{"importMode":"Legacy"},"name":"1.0","referencePolicy":{"type":"Source"}}]}}
   
                           opendatahub.io/notebook-image-desc=A custom Jupyter Notebook image
                           opendatahub.io/notebook-image-name=My Custom Notebook
                           openshift.io/image.dockerRepositoryCheck=2025-03-10T11:02:44Z
   Image Repository:       image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook
   Image Lookup:           local=true
   Unique Images:          1
   Tags:                   1
   
   1.0
     tagged from quay.io/modh/rocm-notebooks@sha256:199367d2946..b411433ffbb5f0988279b10150020af22db
   
     * quay.io/modh/rocm-notebooks@sha256:199367d2946fc8427....1433ffbb5f0988279b10150020af22db
         6 minutes ago

2. To determine the URL for your custom image so that you can reference it when you create a workbench:

   1. Make a note of the values for the Image Repository and the Tags fields from the ImageStream output.

      In the following example, the Image Repository value is image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook and the Tags value is 1.0:

      Example output

      ....
      Image Repository:       image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook
      Image Lookup:           local=true
      Unique Images:          1
      Tags:                   1
      1.0
        tagged from quay.io/modh/rocm-notebooks@sha256:199367d2946..b411433ffbb5f0988279b10150020af22db
      ....

   2. Create a fully-formed image URL by combining the values for the Image Repository and the Tags fields, as shown in the following example:

      image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook:1.0

Procedure

1. In a terminal window, if you are not already logged in to your OpenShift cluster as a cluster administrator, log in as shown in the following example:

   oc login <openshift_cluster_url> -u <admin_username> -p <password>

2. Define the Notebook CRD.

   1. Create a YAML manifest file named notebook.yaml.

   2. Copy the following configuration and paste it in the notebook.yaml file:

      Example Notebook

      apiVersion: kubeflow.org/v1
      kind: Notebook
      metadata:
        annotations:
          notebooks.opendatahub.io/inject-oauth: 'true' 

      1

      
          opendatahub.io/image-display-name: My Custom Notebook 

      2

      
          notebooks.opendatahub.io/oauth-logout-url: 'https://<dashboard_URL>/projects/my-project?notebookLogout=my-workbench'
          opendatahub.io/accelerator-name: ''
          openshift.io/description: '' 

      3

      
          openshift.io/display-name: My Workbench 

      4

      
          notebooks.opendatahub.io/last-image-selection: 'my-custom-notebook:1.0'
          notebooks.kubeflow.org/last_activity_check_timestamp: '2024-07-30T20:43:25Z'
          notebooks.opendatahub.io/last-size-selection: Small
          opendatahub.io/username: 'kube:admin'
          notebooks.kubeflow.org/last-activity: '2024-07-30T20:27:25Z'
          opendatahub.io/connections: 'my-project/my-s3-connection'
          opendatahub.io/connections: 'my-project/my-uri-connection'
          opendatahub.io/connections: 'my-project/my-oci-connection'
        name: my-workbench 

      5

      
        namespace: my-project 

      6

      
        labels:
          kueue.x-k8s.io/queue-name: <local-queue-name> 

      7

      
      spec:
        template:
          spec:
            affinity: {}
            containers:
              - resources: 

      8

      
                  limits:
                    cpu: '2'
                    memory: 8Gi
                  requests:
                    cpu: '1'
                    memory: 8Gi
                readinessProbe:
                  failureThreshold: 3
                  httpGet:
                    path: /notebook/my-project/my-workbench/api
                    port: notebook-port
                    scheme: HTTP
                  initialDelaySeconds: 10
                  periodSeconds: 5
                  successThreshold: 1
                  timeoutSeconds: 1
                name: my-workbench
                livenessProbe:
                  failureThreshold: 3
                  httpGet:
                    path: /notebook/my-project/my-workbench/api
                    port: notebook-port
                    scheme: HTTP
                  initialDelaySeconds: 10
                  periodSeconds: 5
                  successThreshold: 1
                  timeoutSeconds: 1
                env: 

      9

      
                  - name: NOTEBOOK_ARGS
                    value: |-
                      --ServerApp.port=8888
                      --ServerApp.token=''
                      --ServerApp.password=''
                      --ServerApp.base_url=/notebook/my-project/my-workbench
                      --ServerApp.quit_button=False
                      --ServerApp.tornado_settings={"user":"<user>","hub_host":"<dashboard_URL>", "hub_prefix":"/projects/my-project"}
                  - name: JUPYTER_IMAGE
                    value: 'image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook:1.0'
                  - name: PIP_CERT
                    value: /etc/pki/tls/custom-certs/ca-bundle.crt
                  - name: REQUESTS_CA_BUNDLE
                    value: /etc/pki/tls/custom-certs/ca-bundle.crt
                  - name: SSL_CERT_FILE
                    value: /etc/pki/tls/custom-certs/ca-bundle.crt
                  - name: PIPELINES_SSL_SA_CERTS
                    value: /etc/pki/tls/custom-certs/ca-bundle.crt
                  - name: GIT_SSL_CAINFO
                    value: /etc/pki/tls/custom-certs/ca-bundle.crt
                ports:
                  - containerPort: 8888
                    name: notebook-port
                    protocol: TCP
                imagePullPolicy: Always
                volumeMounts:
                  - mountPath: /opt/app-root/src
                    name: my-workbench
                  - mountPath: /dev/shm
                    name: shm
                  - mountPath: /etc/pki/tls/custom-certs/ca-bundle.crt
                    name: trusted-ca
                    readOnly: true
                    subPath: ca-bundle.crt
                image: 'image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook:1.0' 

      10

      
                workingDir: /opt/app-root/src
              - resources: 

      11

      
                  limits:
                    cpu: 100m
                    memory: 64Mi
                  requests:
                    cpu: 100m
                    memory: 64Mi
                readinessProbe:
                  failureThreshold: 3
                  httpGet:
                    path: /oauth/healthz
                    port: oauth-proxy
                    scheme: HTTPS
                  initialDelaySeconds: 5
                  periodSeconds: 5
                  successThreshold: 1
                  timeoutSeconds: 1
                name: oauth-proxy
                livenessProbe:
                  failureThreshold: 3
                  httpGet:
                    path: /oauth/healthz
                    port: oauth-proxy
                    scheme: HTTPS
                  initialDelaySeconds: 30
                  periodSeconds: 5
                  successThreshold: 1
                  timeoutSeconds: 1
                env:
                  - name: NAMESPACE
                    valueFrom:
                      fieldRef:
                        fieldPath: metadata.namespace
                ports:
                  - containerPort: 8443
                    name: oauth-proxy
                    protocol: TCP
                imagePullPolicy: Always
                volumeMounts:
                  - mountPath: /etc/oauth/config
                    name: oauth-config
                  - mountPath: /etc/tls/private
                    name: tls-certificates
                image: 'registry.redhat.io/openshift4/ose-oauth-proxy-rhel9@sha256:ca21e218e26c46e3c63d926241846f8f307fd4a586cc4b04147da49af6018ef5'
                args:
                  - '--provider=openshift'
                  - '--https-address=:8443'
                  - '--http-address='
                  - '--openshift-service-account=my-workbench'
                  - '--cookie-secret-file=/etc/oauth/config/cookie_secret'
                  - '--cookie-expire=24h0m0s'
                  - '--tls-cert=/etc/tls/private/tls.crt'
                  - '--tls-key=/etc/tls/private/tls.key'
                  - '--upstream=http://localhost:8888'
                  - '--upstream-ca=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt'
                  - '--email-domain=*'
                  - '--skip-provider-button'
                  - '--openshift-sar={"verb":"get","resource":"notebooks","resourceAPIGroup":"kubeflow.org","resourceName":"my-workbench","namespace":"$(NAMESPACE)"}'
                  - '--logout-url=<dashboard_URL>/projects/my-project?notebookLogout=my-workbench'
            enableServiceLinks: false
            serviceAccountName: my-workbench
            volumes:
              - name: my-workbench
                persistentVolumeClaim:
                  claimName: my-workbench
              - emptyDir:
                  medium: Memory
                name: shm
              - configMap:
                  items:
                    - key: ca-bundle.crt
                      path: ca-bundle.crt
                  name: workbench-trusted-ca-bundle
                  optional: true
                name: trusted-ca
              - name: oauth-config
                secret:
                  defaultMode: 420
                  secretName: my-workbench-oauth-config
              - name: tls-certificates
                secret:
                  defaultMode: 420
                  secretName: my-workbench-tls

      The example YAML file includes the following information:

      1

      The inject-oauth annotation generates other OAUTH-based configurations, such as, the oauth-proxy, automatically. The default value is true.

      2

      The Notebook image name is visible in the OpenShift AI dashboard. In this example, the image name is My custom notebook. Optionally, you can name the image according to your use case.

      3

      An optional description of the workbench.

      4

      The workbench name that is displayed in the OpenShift AI dashboard. In this example, the display name is My Workbench.

      5

      The name for the workbench. In this example, the workbench name is my-workbench.

      6

      The project for the workbench. In this example, the project name is my-project.

      7

      To queue your workbench (Notebook) Pods and manage their resources, add the kueue.x-k8s.io/queue-name label to the spec.template.metadata.labels of the Notebook CR. Set the value to the name of an existing LocalQueue in your project. This is required only if your project is enabled for Kueue.

      8

      The deployment size for the container. You can set limits and requests values for CPU and memory.

      9

      Environment variables for configuring values, for example, for Jupyter Notebook arguments and SSL/TLS certificates.

      10

      The Notebook image. In this example, image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook:1.0 is the Notebook image. You can select the image version based on the packages included in the image.

      11

      The inject-oauth annotation configures the oauth-proxy container section of the Notebook.

3. Edit the notebooks.opendatahub.io/oauth-logout-url field, annotated as (1) in the following example. Replace my-project with the name of the project that you created.

   Example Notebook

   apiVersion: kubeflow.org/v1
   kind: Notebook
   metadata:
     annotations:
       ...
       notebooks.opendatahub.io/oauth-logout-url: '<dashboard_URL>/projects/my-project?notebookLogout=my-workbench' 

   1

   
       ...

4. Edit the --logout-url= field, annotated as (1) in the following example. Replace my-project with the name of the project that you created.

   Example Notebook

   apiVersion: kubeflow.org/v1
   kind: Notebook
   metadata:
     annotations:
     ...
   spec:
     template:
       spec:
         affinity: {}
         containers:
         ...
         - resources:
         ...
          args:
          - '--logout-url=<dashboard_URL>/projects/my-project?notebookLogout=my-workbench' 

   1

   
          ...

5. Edit the value field of the JUPYTER_IMAGE environment variable, annotated as (1) in the following example. Replace the image URL with the URL of the custom image that you created.

   Example Notebook

   apiVersion: kubeflow.org/v1
   kind: Notebook
   metadata:
     annotations:
     ...
   spec:
     template:
       spec:
         affinity: {}
         containers:
         ...
         - resources:
         ...
         env:
         ...
         - name: JUPYTER_IMAGE
           value: 'image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook:1.0' 

   1

6. Edit the image field, annotated as (1) in the following example. Replace the image URL with the URL of the custom image that you created.

   Example Notebook

   apiVersion: kubeflow.org/v1
   kind: Notebook
   metadata:
     annotations:
     ...
   spec:
     template:
       spec:
         affinity: {}
         containers:
         ...
         - resources:
         ...
         env:
         ...
         ports:
         ..
         imagePullPolicy: Always
         volumeMounts:
         ...
         image: 'image-registry.openshift-image-registry.svc:5000/redhat-ods-applications/my-custom-notebook:1.0' 

   1

   
         workingDir: /opt/app-root/src
         ...

7. To create the Notebook CR, run the following command, where the Notebook CRD YAML manifest filename is notebook.yaml.

   oc create -f notebook.yaml