/workbench-manage Skill

Create and manage Jupyter notebook workbenches on Red Hat OpenShift AI. Handles the full workbench lifecycle: listing available notebook images, creating Notebook CRs with configurable CPU/memory/GPU resources, provisioning PVC storage, starting and stopping workbenches, and deleting them with proper data loss warnings.

Prerequisites

Required MCP Server: openshift (OpenShift MCP Server)

Required MCP Tools (from openshift):

• resources_get - Inspect Notebook CR details, ImageStream details, check node GPU availability
• resources_list - List ImageStreams for notebook image discovery, list PVCs, list Notebooks
• resources_create_or_update - Create/update Notebook CR, PVC, patch annotations for start/stop (OpenShift fallback)
• resources_delete - Delete Notebook CR, PVC (OpenShift fallback for delete operations)
• events_list - Check pod events when workbench is stuck
• pods_list - Check workbench pod status

Preferred MCP Server: rhoai (RHOAI MCP Server) — used when available, automatic OpenShift fallback on failure

Preferred MCP Tools (from rhoai):

• list_data_science_projects - Validate namespace is an RHOAI Data Science Project
• list_workbenches - List existing workbenches in a project
• get_workbench - Get workbench details (status, image, resources, storage)
• create_workbench - Create a new Notebook CR with image, resources, and storage
• start_workbench - Start a stopped workbench. Known issue: may fail with "Unsupported Media Type" — use annotation patch fallback.
• stop_workbench - Stop a running workbench. Known issue: may fail — use annotation patch fallback.
• delete_workbench - Delete a workbench. Known issue: may return "Dangerous operations are disabled" — use resources_delete fallback.
• get_workbench_url - Get the OAuth-protected notebook URL
• list_storage - List PVCs in the project
• create_storage - Create a PVC for workbench storage
• delete_storage - Delete a PVC
• list_data_connections - List data connections available to attach

Common prerequisites (KUBECONFIG, OpenShift+RHOAI cluster, verification protocol): See skill-conventions.md.

Fallback templates: See openshift-fallback-templates.md for OpenShift YAML templates used when RHOAI tools are unavailable.

Important: Do NOT use list_notebook_images (from rhoai) — it returns incorrect hardcoded image names that cause broken deployments. Always use the ImageStream lookup pattern described below.

Additional cluster requirements:

• Target namespace is an RHOAI Data Science Project (label: opendatahub.io/dashboard: "true")

When to Use This Skill

Use this skill when you need to:

• Create a new Jupyter notebook workbench for a data scientist
• List available notebook images (PyTorch, TensorFlow, Standard Data Science, etc.)
• Start or stop an existing workbench
• List workbenches in a project and check their status
• Delete a workbench and its associated storage
• Provision persistent storage for a workbench

Do NOT use this skill when:

• You need to create a Data Science Project first (use /ds-project-setup)
• You want to deploy a model for inference (use /model-deploy)
• You need to manage data science pipelines (use /pipeline-manage)
• You need to troubleshoot a model deployment (use /debug-inference)

Workflow

Step 1: Determine Intent

Ask the user what they want to do:

• Create a new workbench
• Start / Stop an existing workbench
• List workbenches in a project
• Delete a workbench

Ask for the target namespace (required for all operations).

Validate namespace is a Data Science Project:

MCP Tool: list_data_science_projects (from rhoai)

Parameters: none

Verify the user-specified namespace appears in the project list. If not, report: "Namespace [name] is not an RHOAI Data Science Project. Use /ds-project-setup to create one."

Route to the appropriate sub-workflow:

• Create -> Step 2
• Start/Stop -> Step 5
• List -> Use list_workbenches (fallback: resources_list from openshift), display results, done
• Delete -> Step 6

Step 2: Gather Configuration (Create)

Notebook Image Discovery (replaces list_notebook_images which returns incorrect names):

Step 1: List notebook ImageStreams:

MCP Tool: resources_list (from openshift)

• apiVersion: image.openshift.io/v1, kind: ImageStream, namespace: redhat-ods-applications, labelSelector: opendatahub.io/notebook-image=true

Step 2: For each ImageStream, get details:

MCP Tool: resources_get (from openshift)

Extract from each ImageStream:

• .metadata.name — the actual image name (e.g., pytorch, NOT jupyter-pytorch-notebook)
• .spec.tags[].name — available tags (e.g., 2024.1)
• .spec.tags[].annotations["opendatahub.io/notebook-image-name"] — display name
• .spec.tags[].from.name — the full image reference to use in the Notebook CR

Present to user as a selection table showing Image Name, Tag, and Display Name.

See openshift-fallback-templates.md for the complete pattern.

Present available images in a table:

Ask the user for workbench configuration:

• Workbench name: DNS-compatible name (lowercase, hyphens, max 63 chars)
• Image: Selection from the available images list
• CPU: Number of CPU cores (default: 2)
• Memory: Memory allocation (default: 8Gi)
• Storage size: PVC size for persistent storage (default: 20Gi)
• GPU (optional): Number of GPUs to attach (e.g., 1)

Display configuration table:

WAIT for user to confirm or modify the configuration.

Step 3: Provision Storage (Create)

Check existing storage:

MCP Tool: list_storage (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED

If rhoai unavailable or returns error: Use resources_list/resources_create_or_update/resources_delete (from openshift) for PersistentVolumeClaim resources. See openshift-fallback-templates.md.

If a suitable PVC already exists, ask user if they want to reuse it or create a new one.

Create PVC for workbench storage:

MCP Tool: create_storage (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: PVC name (default: [workbench-name]-storage) - REQUIRED
• size: storage size from Step 2 (e.g., "20Gi") - REQUIRED
• access_mode: "ReadWriteOnce" - REQUIRED (default, single-pod access)

If rhoai unavailable or returns error: Use resources_list/resources_create_or_update/resources_delete (from openshift) for PersistentVolumeClaim resources. See openshift-fallback-templates.md.

Verify creation:

MCP Tool: list_storage (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED

Confirm the PVC appears and is in Bound or Pending state.

Error Handling:

• If PVC name already exists -> Ask: "PVC [name] already exists. Reuse it or create with a different name?"
• If StorageClass not available -> Report: "Default StorageClass not configured. Contact your cluster administrator."
• If quota exceeded -> Report namespace storage quota limits

Step 4: Create Workbench (Create)

MCP Tool: create_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name from Step 2 - REQUIRED
• image: selected notebook image name from Step 2 - REQUIRED
• cpu: CPU cores (e.g., "2") - REQUIRED
• memory: memory allocation (e.g., "8Gi") - REQUIRED
• storage_size: PVC storage size (e.g., "20Gi") - REQUIRED

Monitor workbench startup by polling status:

MCP Tool: get_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

Check until status shows the workbench is running. If status does not become ready within a reasonable polling window (3-4 checks), proceed to report current status and advise user to check back.

Get notebook URL:

MCP Tool: get_workbench_url (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

Error Handling:

• If workbench name already exists -> Report: "Workbench [name] already exists. Choose a different name or manage the existing one."
• If image not found -> Re-run the ImageStream lookup pattern and suggest available alternatives
• If RBAC error -> Report insufficient permissions to create Notebook CRs
• If GPU unavailable -> Report: "Requested GPU resources not available on cluster nodes. Reduce GPU count or wait for resources."

Report to user:

Suggest next steps:

• Access the notebook at the provided URL (OpenShift authentication required)
• Use /ds-project-setup to add data connections to the project
• Use /model-deploy when ready to deploy a trained model

Step 5: Manage Lifecycle (Start/Stop)

List workbenches to identify the target:

MCP Tool: list_workbenches (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED

If rhoai unavailable or returns error: Use resources_list (from openshift) with apiVersion: kubeflow.org/v1, kind: Notebook, namespace: [namespace].

If user did not specify a workbench name, present the list and ask which one to manage.

For Start:

Confirm the workbench is currently stopped. If already running, report its URL and current status.

MCP Tool: start_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

If rhoai unavailable or returns error (e.g., "Unsupported Media Type"): Patch the Notebook CR annotation via resources_create_or_update (from openshift) to remove the kubeflow-resource-stopped annotation (set to null or empty). See openshift-fallback-templates.md.

MCP Tool: get_workbench_url (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

Output to user: "Workbench [name] started. Access it at: [url]"

For Stop:

WAIT for user confirmation: "Workbench [name] is currently running. Stopping it will interrupt any active sessions. Unsaved work in the notebook may be lost. Proceed? (yes/no)"

MCP Tool: stop_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

If rhoai unavailable or returns error: Patch the Notebook CR via resources_create_or_update (from openshift) to set annotation kubeflow-resource-stopped: "true". See openshift-fallback-templates.md.

Verify state change:

MCP Tool: get_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

If rhoai unavailable or returns error: Use resources_get (from openshift) with apiVersion: kubeflow.org/v1, kind: Notebook, name: [name], namespace: [namespace].

Output to user: "Workbench [name] stopped. Persistent storage is preserved. Use /workbench-manage to start it again."

Error Handling:

• If workbench not found -> List available workbenches and ask user to select
• If already in target state -> Report current state (e.g., "Workbench is already running")

Step 6: Delete Workbench

Get workbench details:

MCP Tool: get_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

If rhoai unavailable or returns error: Use resources_get (from openshift) with apiVersion: kubeflow.org/v1, kind: Notebook, name: [name], namespace: [namespace].

Display workbench details and data loss warning:

WARNING: Deleting this workbench will remove the Notebook CR. If the workbench is running, it will be stopped first. Any unsaved notebook work will be lost.

Ask: "Delete workbench [name]? This action cannot be undone. (yes/no)"

WAIT for explicit confirmation.

MCP Tool: delete_workbench (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: workbench name - REQUIRED

If rhoai unavailable or returns error (e.g., "Dangerous operations are disabled"): Use resources_delete (from openshift) with apiVersion: kubeflow.org/v1, kind: Notebook, name: [workbench-name], namespace: [namespace]. WAIT for user confirmation before deleting — warn about data loss.

Associated storage cleanup (separate confirmation):

Ask: "The PVC [pvc_name] ([size]) associated with this workbench still exists. Delete it too? WARNING: All data in this volume will be permanently lost. (yes/no)"

WAIT for explicit confirmation.

If user confirms PVC deletion:

MCP Tool: delete_storage (from rhoai)

Parameters:

• namespace: target namespace - REQUIRED
• name: PVC name - REQUIRED

If rhoai unavailable or returns error: Use resources_list/resources_create_or_update/resources_delete (from openshift) for PersistentVolumeClaim resources. See openshift-fallback-templates.md.

If user declines, report: "PVC [pvc_name] preserved. It can be reattached to a new workbench."

Output to user: "Workbench [name] deleted. [PVC deleted / PVC preserved]."

Common Issues

For common issues (GPU scheduling, OOMKilled, image pull errors, RBAC), see common-issues.md.

Issue 1: Notebook Image Not Found

Error: create_workbench fails with image not found or image reference is invalid

Cause: The selected image name does not match any available notebook image, or the image registry is unreachable.

Solution:

1. Run the ImageStream lookup pattern to see current available images
2. Verify the exact image name (case-sensitive)
3. If no images are listed, the RHOAI operator may not have imported notebook images -- contact cluster administrator

Issue: Workbench Created with Wrong Image (ImagePullBackOff)

Error: Workbench pod stuck in ImagePullBackOff after creation

Cause: The list_notebook_images tool returned incorrect image names (e.g., jupyter-pytorch-notebook instead of the actual ImageStream name pytorch).

Solution: This tool has been replaced. Use the ImageStream lookup pattern via OpenShift MCP to discover correct image names. Patch the stuck Notebook CR with the correct image reference from the ImageStream, then delete the stuck pod to force rescheduling.

See common-issues.md for details.

Issue 2: PVC Binding Failure

Error: PVC remains in Pending state, workbench cannot start

Cause: The default StorageClass does not support the requested access mode, or no StorageClass is configured.

Solution:

1. Check available StorageClasses via resources_get (from openshift) on storageclasses.storage.k8s.io
2. Use ReadWriteOnce access mode (most widely supported)
3. If ReadWriteMany is required, verify the StorageClass supports it (e.g., NFS, CephFS)
4. Contact cluster administrator if no StorageClass is available

Issue 3: Workbench Stuck in Starting

Error: Workbench status remains in a starting/initializing state for an extended period

Cause: Pod scheduling issues, image pull errors, or resource constraints.

Solution:

1. Use events_list (from openshift) filtered by namespace to check for pod events
2. Common causes:
   • ImagePullBackOff: Image registry unreachable or credentials missing
   • Insufficient cpu/memory: Reduce resource requests or free up cluster resources
   • FailedScheduling: Node taints or affinity rules preventing scheduling
3. If GPU is requested, verify GPU nodes have available capacity

Dependencies

MCP Tools

See Prerequisites for the complete list of required and optional MCP tools.

Related Skills

• /ds-project-setup - Create a Data Science Project (prerequisite: namespace must exist)
• /model-deploy - Deploy a trained model from the workbench
• /ai-observability - Check GPU inventory before requesting GPU workbenches

Reference Documentation

• skill-conventions.md - Shared prerequisite, HITL, and security conventions

Example Usage

User: "Create a PyTorch notebook workbench in my ml-team project with 4 CPUs and a GPU"

Skill response: Validates ml-team is an RHOAI project, lists available notebook images, presents configuration table (PyTorch image, 4 CPU, 8Gi memory, 1 GPU, 20Gi storage), provisions PVC storage, creates workbench, monitors startup, and returns the notebook URL.

Critical: Human-in-the-Loop Requirements

See skill-conventions.md for general HITL and security conventions.

Skill-specific checkpoints:

• Before creating workbench (Step 4): display full configuration table, confirm
• Before stopping a workbench (Step 5): warn about unsaved work, confirm
• Before deleting a workbench (Step 6): display details, warn about data loss, confirm
• Before deleting associated PVC (Step 6): separate confirmation with permanent data loss warning
• NEVER auto-delete workbenches or storage
• NEVER stop a running workbench without confirmation (user may have unsaved notebook work)