kubeflow / kubeflow/notebooks

[TASK] Documentation for migrating Notebook workloads to WorkspaceKind + Workspace model

Open
#864 2 comments 0 reactions 0 assignees View on GitHub
area/docs area/v2 kind/plan-task
Dominant language
No language data
Stars
84
Forks
149
Avg merge
5d 15h
Merged PRs (30d)
29

Description

### Certification

- [x] I certify I am an Epic Owner for Kubeflow Notebooks 2.0 and expected to create planning-related issues.

### Description

## Description

Create documentation that helps Joel understand how to migrate their existing Kubeflow Notebooks v1 workloads to the v2 architecture. The v1 `Notebook` custom resource is replaced by the dual-resource model of `WorkspaceKind` (cluster-scoped templates) and `Workspace` (user instances).

The documentation should build intuition for making migration decisions rather than providing prescriptive step-by-step instructions. There is no single correct migration path—the right approach depends on existing configurations, organizational policies, and resource allocation strategies.

### Content to Write

1. **Conceptual Overview**
- Explain the shift from single-resource (v1 Notebook) to dual-resource (v2 WorkspaceKind + Workspace) model
- Describe why v2 separates "what a workspace can be" from "what a user wants"
- Outline benefits of the new model (standardization, governance, flexibility)

2. **Field Mapping Reference**
- Create a table mapping v1 Notebook spec fields to v2 WorkspaceKind/Workspace equivalents
- Add callouts for fields that require design decisions or work differently

3. **WorkspaceKind Design Patterns**
- Document common organizational approaches with trade-offs (not recommendations):
- Tool-based (JupyterLab, RStudio, VSCode)
- Resource-tier-based (small-cpu, large-gpu)
- Team-based
- Hybrid approaches

4. **Decision Framework**
- Provide guiding questions to help Joel evaluate their environment:
- How do users currently choose their notebook configuration?
- What constraints does the organization want to enforce?
- How granular should image/pod config options be?
- What labeling strategy supports future compatibility selector rules?

5. **Migration Considerations**
- Assessing current v1 notebook usage patterns
- Planning for user communication and training
- Phased rollout strategies
- Handling in-flight workloads during transition

### Writing Guidelines

- Use guidance language ("consider", "depending on your environment", "one approach is") rather than absolutes ("you must", "always", "never")
- Present trade-offs, not best practices
- Acknowledge that migration decisions depend on organizational context
- Keep the tone helpful and empathetic to Joel's challenges

### Location

Documentation should be added to the appropriate location in the project's docs (coordinate with maintainers on exact path).

### Acceptance Criteria

- [ ] Documentation explains the conceptual shift from v1 Notebook to v2 WorkspaceKind + Workspace
- [ ] Field mapping table helps Joel understand where v1 configurations map in v2
- [ ] Multiple WorkspaceKind design patterns are documented with trade-offs
- [ ] Decision framework questions help Joel evaluate their specific environment
- [ ] Language avoids absolutes in favor of guidance
- [ ] Documentation explicitly acknowledges there is no single correct migration path

Contributor guide

Open the contributing guide

Research direction

Start by locating the project's existing documentation and the v1 Notebook, WorkspaceKind, and Workspace resource definitions. Use those entry points to build the field mapping and compare the proposed design patterns and migration considerations. Done means the documentation covers every acceptance criterion, presents trade-offs without absolutes, and acknowledges that migration depends on organizational context.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes
Domain
devops, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.